mirrors/dotdrop
1
0
Fork 0
mirror of https://github.com/deadc0de6/dotdrop.git synced 2026-02-04 19:09:44 +00:00
Code Activity

update usage doc

Browse Source
This commit is contained in:
deadc0de6
2020-10-10 13:10:14 +02:00
parent a77b7d0a3b
commit f845dd9d42
1 changed files with 77 additions and 79 deletions
Download Patch File Download Diff File Expand all files Collapse all files

156
docs/usage.md
View File

@@ -9,62 +9,31 @@ The basic use of dotdrop is
* import a file/directory to manage (this will copy the files from the filesystem to your `dotpath`): `dotdrop import <somefile>`
* install the dotfiles (will *copy/link* those from your `dotpath` to the filesystem): `dotdrop install`
Then if you happen to update the file/directory directly on the filesystem (add new file/dir, edit content, etc) you can use `update` to mirror back those changes in dotdrop.
Then if you happen to update the file/directory directly on the filesystem (add new file/dir, edit content, etc) you can use the `update` command to mirror back those changes in dotdrop.
For more advanced uses:
* `dotdrop --help` for more options.
* `dotdrop --help` for the cli usage.
* [the example](https://github.com/deadc0de6/dotdrop#getting-started)
## Install dotfiles
Simply run
```bash
$ dotdrop install
```
some available options
* `-t --temp`: install the dotfile(s) to a temporary directory for review (it helps to debug templating issues for example). Note that actions are not executed in that mode.
* `-a --force-actions`: force the execution of actions even if the dotfiles are not installed
For more detail, see the usage with `dotdrop --help`
To ignore specific pattern during installation see [the ignore patterns](config.md#ignore-patterns)
## Compare dotfiles
Compare local dotfiles with the ones stored in dotdrop:
```bash
$ dotdrop compare
```
The diffing is done by `diff` in the backend, one can provide its specific
diff command using the config option `diff_command`.
To ignore specific pattern,
see [the ignore patterns](config.md#ignore-patterns)
It is also possible to install all dotfiles for a specific profile
in a temporary directory in order to manually compare them with
the local version by using `install` and the `-t` switch.
* [the howto](howto/howto.md)
## Import dotfiles
Dotdrop allows to import dotfiles directly from the
filesystem. It will copy the dotfile and update the
config file automatically.
The `import` command imports dotfiles to be managed by dotdrop.
It copies the dotfile to your `dotpath` and updates the config file with the new entry.
Note that dotdrop will dereference all symlinks
when importing a file or directory.
Note that dotdrop will dereference all symlinks when importing a file or directory.
For example to import `~/.xinitrc`
```bash
$ dotdrop import ~/.xinitrc
-> "/home/user/.xinitrc" imported
1 file(s) imported.
```
You can control how the dotfile key is generated in the config file
with the option `longkey` (per default to *false*).
with the config entry `longkey` (per default to *false*).
Two formats are available:
@@ -81,7 +50,7 @@ Importing `~/.mutt/colors` and then `~/.vim/colors` will result in
* `d_colors` and `d_vim_colors` in the short format
* `d_mutt_colors` and `d_vim_colors` in the long format
Dotfile can be imported as a different file with the use
Dotfiles can be imported as a different file with the use
of the command line switch `--as` (effectively selecting the `src` part
of the dotfile in the config). It is however recommended
to use [templating](templating.md) to avoid duplicates and optimize
@@ -90,8 +59,49 @@ dotfiles management.
$ dotdrop import ~/.zshrc --as=~/.zshrc.test
```
For more options, see the usage with `dotdrop --help`
## Install dotfiles
The `install` command installs/deploys dotfiles managed by dotdrop from the `dotpath` to their destinations.
```bash
$ dotdrop install
```
The dotfile will be installed only if it differs from the version already present on its destination.
some available options
* `-t --temp`: install the dotfile(s) to a temporary directory for review (it helps to debug templating issues for example).
Note that actions are not executed in that mode.
* `-a --force-actions`: force the execution of actions even if the dotfiles are not installed
* `-f --force`: do not ask any confirmation
To ignore specific pattern during installation see [the ignore patterns](config.md#ignore-patterns)
For more options, see the usage with `dotdrop --help`
## Compare dotfiles
The `compare` command compares dotfiles on their destination with the one stored in your `dotpath`.
```bash
$ dotdrop compare
```
The diffing is done by the unix tool `diff` in the backend, one can provide its specific
diff command using the config entry `diff_command`.
To ignore specific pattern, see [the ignore patterns](config.md#ignore-patterns)
It is also possible to install all dotfiles for a specific profile
in a temporary directory in order to manually compare them with
the local version by using `install` and the `-t` switch.
For more options, see the usage with `dotdrop --help`
## List profiles
The `profiles` command lists defined profiles in the config file
```bash
$ dotdrop profiles
```
@@ -105,55 +115,47 @@ The default profile can also be changed by defining the
## List dotfiles
The following command lists the different dotfiles
configured for a specific profile:
The `files` command lists the dotfiles declared for a specific profile.
```bash
$ dotdrop files --profile=<some-profile>
```
For example:
```
Dotfile(s) for profile "some-profile":
f_vimrc (file: "vimrc", link: nolink)
-> ~/.vimrc
f_dunstrc (file: "config/dunst/dunstrc", link: nolink)
-> ~/.config/dunst/dunstrc
$ dotdrop files --profile=some-profile
f_xinitrc
-> dst: /home/user/.xinitrc
-> src: /home/user/dotdrop/dotfiles/xinitrc
-> link: nolink
```
By using the `-T --template` switch, only the dotfiles that
are using [jinja2](https://palletsprojects.com/p/jinja/) directives are listed.
are using [templating](templating.md) are listed.
It is also possible to list all files related to each dotfile entries
by invoking the `detail` command, for example:
```bash
$ dotdrop detail
dotfiles details for profile "some-profile":
f_tmux.conf (dst: "~/.tmux.conf", link: nolink)
-> /home/user/dotfiles/tmux.conf (template:no)
f_vimrc (dst: "~/.vimrc", link: nolink)
-> /home/user/dotfiles/vimrc (template:no)
f_xinitrc (dst: "/home/user/.xinitrc", link: nolink)
-> /home/user/dotdrop/dotfiles/xinitrc (template:no)
```
This is especially useful when the dotfile entry is a directory
and one wants to have information on the different files (is it
a templated file, etc).
and one wants to have information on the different files it contains
(does a specific file uses templating, etc).
For more options, see the usage with `dotdrop --help`
## Update dotfiles
Dotfiles managed by dotdrop can be updated using the `update` command. When updating, only
dotfiles that have differences with the stored version are updated.
A confirmation is requested from the user before any overwrite/update unless the
`-f --force` switch is used.
The `update` commands will updates a dotfile managed by dotdrop by copying the dotfile
from the filesystem to the `dotpath`. Only dotfiles that have differences with the stored version are updated.
A confirmation is requested from the user before any overwrite/update unless the `-f --force` switch is used.
Either provide the path of the file containing the new version of the dotfile or
provide the dotfile key to update (as found in the config file) along with the `-k --key` switch.
When using the `-k --key` switch and no key is provided, all dotfiles for that profile are updated.
```bash
# update by path
## update by path
$ dotdrop update ~/.vimrc
# update by key with the --key switch
## update by key with the --key switch
$ dotdrop update --key f_vimrc
```
@@ -180,9 +182,9 @@ $ git diff
The dotfile must be manually updated, three solutions can be used to identify the
changes to apply to the template:
* Use dotdrop's `compare` command
* Use the `compare` command
```bash
# use compare to identify change(s)
## use compare to identify change(s)
$ dotdrop compare --file=~/.vimrc
```
@@ -190,7 +192,7 @@ $ dotdrop compare --file=~/.vimrc
to manually patch the template file using a temporary generated version of the template
(this isn't a bullet proof solution and might need manual checking)
```bash
# get an ad-hoc solution to manually patch the template
## get an ad-hoc solution to manually patch the template
$ dotdrop update --show-patch ~/.vimrc
[WARN] /home/user/dotfiles/vimrc uses template, update manually
[WARN] try patching with: "diff -u /tmp/dotdrop-sbx6hw0r /home/user/.vimrc | patch /home/user/dotfiles/vimrc"
@@ -199,18 +201,12 @@ $ dotdrop update --show-patch ~/.vimrc
* Install the dotfiles to a temporary directory (using the `install` command and the
`-t` switch) and compare the generated dotfile with the local one.
```bash
# use install to identify change(s)
$ dotdrop install -t
## use install to identify change(s)
$ dotdrop install -t -t f_vimrc
Installed to tmp /tmp/dotdrop-6ajz7565
$ diff ~/.vimrc /tmp/dotdrop-6ajz7565/home/user/.vimrc
```
It is also possible to install only specific dotfiles by providing their keys
in the command line. For example for a dotfile having a key `f_zshrc` in the config file.
```bash
$ dotdrop install -t f_zshrc
```
## Remove dotfiles
The command `remove` allows to stop managing a specific dotfile with
@@ -219,6 +215,8 @@ dotdrop. It will:
* remove the entry in the config file (under `dotfiles` and `profile`)
* remove the file from the `dotpath`
For more options, see the usage with `dotdrop --help`
## Environment variables
Following environment variables can be used to specify different CLI options.