From f845dd9d424d271f003f354714f359f872bb8b86 Mon Sep 17 00:00:00 2001 From: deadc0de6 Date: Sat, 10 Oct 2020 13:10:14 +0200 Subject: [PATCH] update usage doc --- docs/usage.md | 156 +++++++++++++++++++++++++------------------------- 1 file changed, 77 insertions(+), 79 deletions(-) diff --git a/docs/usage.md b/docs/usage.md index b19d33e..396f361 100644 --- a/docs/usage.md +++ b/docs/usage.md @@ -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 ` * 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= -``` - -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.