mirrors/dotdrop
1
0
Fork 0
mirror of https://github.com/deadc0de6/dotdrop.git synced 2026-02-15 17:20:05 +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>` * 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` * 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: For more advanced uses:
* `dotdrop --help` for more options. * `dotdrop --help` for the cli usage.
* [the example](https://github.com/deadc0de6/dotdrop#getting-started) * [the example](https://github.com/deadc0de6/dotdrop#getting-started)
* [the howto](howto/howto.md)
## 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.
## Import dotfiles ## Import dotfiles
Dotdrop allows to import dotfiles directly from the The `import` command imports dotfiles to be managed by dotdrop.
filesystem. It will copy the dotfile and update the It copies the dotfile to your `dotpath` and updates the config file with the new entry.
config file automatically.
Note that dotdrop will dereference all symlinks Note that dotdrop will dereference all symlinks when importing a file or directory.
when importing a file or directory.
For example to import `~/.xinitrc` For example to import `~/.xinitrc`
```bash ```bash
$ dotdrop import ~/.xinitrc $ dotdrop import ~/.xinitrc
-> "/home/user/.xinitrc" imported
1 file(s) imported.
``` ```
You can control how the dotfile key is generated in the config file 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: 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_colors` and `d_vim_colors` in the short format
* `d_mutt_colors` and `d_vim_colors` in the long 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 command line switch `--as` (effectively selecting the `src` part
of the dotfile in the config). It is however recommended of the dotfile in the config). It is however recommended
to use [templating](templating.md) to avoid duplicates and optimize to use [templating](templating.md) to avoid duplicates and optimize
@@ -90,8 +59,49 @@ dotfiles management.
$ dotdrop import ~/.zshrc --as=~/.zshrc.test $ 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 ## List profiles
The `profiles` command lists defined profiles in the config file
```bash ```bash
$ dotdrop profiles $ dotdrop profiles
``` ```
@@ -105,55 +115,47 @@ The default profile can also be changed by defining the
## List dotfiles ## List dotfiles
The following command lists the different dotfiles The `files` command lists the dotfiles declared for a specific profile.
configured for a specific profile:
```bash ```bash
$ dotdrop files --profile=<some-profile> $ dotdrop files --profile=some-profile
``` f_xinitrc
-> dst: /home/user/.xinitrc
For example: -> src: /home/user/dotdrop/dotfiles/xinitrc
``` -> link: nolink
Dotfile(s) for profile "some-profile":
f_vimrc (file: "vimrc", link: nolink)
-> ~/.vimrc
f_dunstrc (file: "config/dunst/dunstrc", link: nolink)
-> ~/.config/dunst/dunstrc
``` ```
By using the `-T --template` switch, only the dotfiles that 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 It is also possible to list all files related to each dotfile entries
by invoking the `detail` command, for example: by invoking the `detail` command, for example:
```bash ```bash
$ dotdrop detail $ dotdrop detail
dotfiles details for profile "some-profile": dotfiles details for profile "some-profile":
f_tmux.conf (dst: "~/.tmux.conf", link: nolink) f_xinitrc (dst: "/home/user/.xinitrc", link: nolink)
-> /home/user/dotfiles/tmux.conf (template:no) -> /home/user/dotdrop/dotfiles/xinitrc (template:no)
f_vimrc (dst: "~/.vimrc", link: nolink)
-> /home/user/dotfiles/vimrc (template:no)
``` ```
This is especially useful when the dotfile entry is a directory This is especially useful when the dotfile entry is a directory
and one wants to have information on the different files (is it and one wants to have information on the different files it contains
a templated file, etc). (does a specific file uses templating, etc).
For more options, see the usage with `dotdrop --help`
## Update dotfiles ## Update dotfiles
Dotfiles managed by dotdrop can be updated using the `update` command. When updating, only The `update` commands will updates a dotfile managed by dotdrop by copying the dotfile
dotfiles that have differences with the stored version are updated. 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 A confirmation is requested from the user before any overwrite/update unless the `-f --force` switch is used.
`-f --force` switch is used.
Either provide the path of the file containing the new version of the dotfile or 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. 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. When using the `-k --key` switch and no key is provided, all dotfiles for that profile are updated.
```bash ```bash
# update by path ## update by path
$ dotdrop update ~/.vimrc $ dotdrop update ~/.vimrc
# update by key with the --key switch ## update by key with the --key switch
$ dotdrop update --key f_vimrc $ 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 The dotfile must be manually updated, three solutions can be used to identify the
changes to apply to the template: changes to apply to the template:
* Use dotdrop's `compare` command * Use the `compare` command
```bash ```bash
# use compare to identify change(s) ## use compare to identify change(s)
$ dotdrop compare --file=~/.vimrc $ 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 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) (this isn't a bullet proof solution and might need manual checking)
```bash ```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 $ dotdrop update --show-patch ~/.vimrc
[WARN] /home/user/dotfiles/vimrc uses template, update manually [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" [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 * Install the dotfiles to a temporary directory (using the `install` command and the
`-t` switch) and compare the generated dotfile with the local one. `-t` switch) and compare the generated dotfile with the local one.
```bash ```bash
# use install to identify change(s) ## use install to identify change(s)
$ dotdrop install -t $ dotdrop install -t -t f_vimrc
Installed to tmp /tmp/dotdrop-6ajz7565 Installed to tmp /tmp/dotdrop-6ajz7565
$ diff ~/.vimrc /tmp/dotdrop-6ajz7565/home/user/.vimrc $ 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 ## Remove dotfiles
The command `remove` allows to stop managing a specific dotfile with 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 entry in the config file (under `dotfiles` and `profile`)
* remove the file from the `dotpath` * remove the file from the `dotpath`
For more options, see the usage with `dotdrop --help`
## Environment variables ## Environment variables
Following environment variables can be used to specify different CLI options. Following environment variables can be used to specify different CLI options.