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

Proofread docs

Browse Source
This commit is contained in:
John T. Wodder II
2021-10-05 12:14:42 -04:00
parent 2c7ac514e0
commit 60550424ca
27 changed files with 624 additions and 631 deletions
Download Patch File Download Diff File Expand all files Collapse all files

140
docs/usage.md
View File

@@ -4,18 +4,18 @@ Run `dotdrop --help` to see all available options.
## Basic usage
The basic use of dotdrop is
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`
* Import a file/directory to manage (this will copy the files from the filesystem to your `dotpath`): `dotdrop import <somefile>`
* Install the dotfiles (this will *copy/link* them 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 the `update` command to mirror back those changes in dotdrop.
Then if you happen to update the file/directory directly on the filesystem (add a 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 the cli usage.
* [the example](https://github.com/deadc0de6/dotdrop#getting-started)
* [the howto](howto/howto.md)
* `dotdrop --help` for the CLI usage.
* [The example](https://github.com/deadc0de6/dotdrop#getting-started)
* [The howto](howto/howto.md)
## Profile
@@ -23,17 +23,17 @@ The default profile used by dotdrop is the *hostname* of the host you are runnin
It can be changed:
* using the command line switch `-p --profile=<profile>`
* by defining it in the env variable `DOTDROP_PROFILE`
* Using the command line switch `-p`/`--profile=<profile>`
* By defining it in the env variable `DOTDROP_PROFILE`
## Import dotfiles
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.
Dotdrop will ask for dereferencing symlinks on import unless `-f --force` is used.
Dotdrop will ask whether to dereference symlinks on import unless `-f`/`--force` is used.
For example to import `~/.xinitrc`
For example, to import `~/.xinitrc`:
```bash
$ dotdrop import ~/.xinitrc
-> "/home/user/.xinitrc" imported
@@ -42,35 +42,35 @@ $ dotdrop import ~/.xinitrc
```
You can control how the dotfile key is generated in the config file
with the config entry `longkey` (per default to *false*).
with the config entry `longkey` (defaults to *false*).
Two formats are available:
* *short format* (default): take the shortest unique path
* *long format*: take the full path
For example `~/.config/awesome/rc.lua` gives
For example, `~/.config/awesome/rc.lua` gives:
* `f_rc.lua` in the short format
* `f_config_awesome_rc.lua` in the long format
Importing `~/.mutt/colors` and then `~/.vim/colors` will result in
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
Dotfiles can be imported as a different file with the use
A dotfile 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
dotfiles management.
dotfile management.
```bash
$ dotdrop import ~/.zshrc --as=~/.zshrc.test
```
To ignore specific pattern during import see [the ignore patterns](config.md#ignore-patterns)
To ignore specific patterns during import, see [the ignore patterns](config.md#ignore-patterns).
For more options, see the usage with `dotdrop --help`
For more options, see the usage with `dotdrop --help`.
## Install dotfiles
@@ -79,49 +79,45 @@ The `install` command installs/deploys dotfiles managed by dotdrop from the `dot
$ dotdrop install
```
The dotfile will be installed only if it differs from the version already present on its destination.
A dotfile will be installed only if it differs from the version already present at its destination.
some available options
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
* `-t`/`--temp`: Install the dotfile(s) to a temporary directory for review (helping to debug templating issues, for example).
Note that actions are not executed in this mode.
* `-a`/`--force-actions`: Force the execution of actions even if the dotfiles are not installed
* `-f`/`--force`: Do not ask for any confirmation
To ignore specific pattern during installation see [the ignore patterns](config.md#ignore-patterns)
To ignore specific patterns during installation, see [the ignore patterns](config.md#ignore-patterns).
For more options, see the usage with `dotdrop --help`
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`.
The `compare` command compares dotfiles at their destinations with the ones stored in your `dotpath`.
```bash
$ dotdrop compare
```
The diffing is done by the unix tool `diff` in the backend, one can provide its specific
The diffing is done with the UNIX tool `diff` as the backend; one can provide a specific
diff command using the config entry `diff_command`.
To ignore specific pattern, see [the ignore patterns](config.md#ignore-patterns)
To ignore specific patterns, see [the ignore patterns](config.md#ignore-patterns).
To completely ignore all files not present in `dotpath` see [ignore missing](#ignore-missing).
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.
To completely ignore all files not present in `dotpath` see [Ignore missing](#ignore-missing).
For more options, see the usage with `dotdrop --help`.
## List profiles
The `profiles` command lists defined profiles in the config file
The `profiles` command lists the profiles defined in the config file.
```bash
$ dotdrop profiles
```
Dotdrop allows to choose which profile to use
Dotdrop allows you to choose which profile to use
with the `--profile` switch if you use something
else than the default (the hostname).
other than the default (the hostname).
The default profile can also be changed by defining the
`DOTDROP_PROFILE` environment variable.
@@ -137,10 +133,10 @@ f_xinitrc
-> link: nolink
```
By using the `-T --template` switch, only the dotfiles that
By using the `-T`/`--template` switch, only the dotfiles that
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 the files related to each dotfile entry
by invoking the `detail` command, for example:
```bash
$ dotdrop detail
@@ -151,19 +147,19 @@ f_xinitrc (dst: "/home/user/.xinitrc", link: nolink)
This is especially useful when the dotfile entry is a directory
and one wants to have information on the different files it contains
(does a specific file uses templating, etc).
(does a specific file uses templating, etc.).
For more options, see the usage with `dotdrop --help`
For more options, see the usage with `dotdrop --help`.
## Update dotfiles
The `update` commands will updates a dotfile managed by dotdrop by copying the dotfile
The `update` command 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.
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.
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
$ dotdrop update ~/.vimrc
@@ -174,16 +170,16 @@ $ dotdrop update --key f_vimrc
If not argument is provided, all dotfiles for the selected profile are updated.
To ignore specific pattern, see [the dedicated page](config.md#ignore-patterns)
To ignore specific patterns, see [the dedicated page](config.md#ignore-patterns).
To completely ignore all files not present in `dotpath` see [ignore missing](#ignore-missing).
To completely ignore all files not present in `dotpath`, see [Ignore missing](#ignore-missing).
There are two cases when updating a dotfile:
### The dotfile doesn't use [templating](templating.md)
The new version of the dotfile is copied to the *dotpath* directory and overwrites
the old version. If git is used to version the dotfiles stored by dotdrop, the git command
the old version. If Git is used to version the dotfiles stored by dotdrop, the Git command
`diff` can be used to view the changes.
```bash
@@ -193,18 +189,18 @@ $ git diff
### The dotfile uses [templating](templating.md)
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:
* Use the `compare` command
* Use the `compare` command:
```bash
## use compare to identify change(s)
$ dotdrop compare --file=~/.vimrc
```
* Call `update` with the `-P --show-patch` switch that will provide with an ad-hoc solution
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)
* Call `update` with the `-P`/`--show-patch` switch, which provides an ad-hoc solution
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
$ dotdrop update --show-patch ~/.vimrc
@@ -213,7 +209,7 @@ $ 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.
`-t` switch) and compare the generated dotfile with the local one:
```bash
## use install to identify change(s)
$ dotdrop install -t -t f_vimrc
@@ -223,17 +219,17 @@ $ diff ~/.vimrc /tmp/dotdrop-6ajz7565/home/user/.vimrc
## Remove dotfiles
The command `remove` allows to stop managing a specific dotfile with
The command `remove` allows you to stop managing a specific dotfile with
dotdrop. It will:
* remove the entry in the config file (under `dotfiles` and `profile`)
* remove the entry from the config file (under `dotfiles` and `profile`)
* remove the file from the `dotpath`
For more options, see the usage with `dotdrop --help`
For more options, see the usage with `dotdrop --help`.
## Concurrency
The command line switch `-w --workers` if set to a value greater than one allows to use
The command line switch `-w`/`--workers`, if set to a value greater than one, allows you to use
multiple concurrent workers to execute an operation. It can be applied to the following
commands:
@@ -244,37 +240,37 @@ commands:
It should be set to a maximum of the number of cores available (usually returned
on linux by the command `nproc`).
It may speed up the operation but cannot be used interractively (it needs `-f --force` to be set
except for `compare`) and cannot be used with `-d --dry`. Also information printed to stdout/stderr
It may speed up the operation but cannot be used interactively (it needs `-f`/`--force` to be set
except for `compare`) and cannot be used with `-d`/`--dry`. Also, information printed to stdout/stderr
will probably be messed up.
**WARNING** this feature hasn't been extensively tested and is to be used at your own risk.
If you try it out and find any issue, please [report it](https://github.com/deadc0de6/dotdrop/issues).
Also if you find it useful and have been able to successfully speed up your operation when using
`-w --workers`, do please also report it [in an issue](https://github.com/deadc0de6/dotdrop/issues).
**WARNING:** This feature hasn't been extensively tested and is to be used at your own risk.
If you try it out and find any issues, please [report them](https://github.com/deadc0de6/dotdrop/issues).
Also, if you find it useful and have been able to successfully speed up your operation when using
`-w`/`--workers`, do please also report it [in an issue](https://github.com/deadc0de6/dotdrop/issues).
## Environment variables
Following environment variables can be used to specify different CLI options.
The following environment variables can be used to specify different CLI options.
Note that CLI switches take precedence over environment variables (except for `DOTDROP_FORCE_NODEBUG`)
* `DOTDROP_PROFILE`: `-p --profile`
* `DOTDROP_PROFILE`: `-p`/`--profile`
```bash
export DOTDROP_PROFILE="my-fancy-profile"
```
* `DOTDROP_CONFIG`: `-c --cfg`
* `DOTDROP_CONFIG`: `-c`/`--cfg`
```bash
export DOTDROP_CONFIG="/home/user/dotdrop/config.yaml"
```
* `DOTDROP_NOBANNER`: `-b --no-banner`
* `DOTDROP_NOBANNER`: `-b`/`--no-banner`
```bash
export DOTDROP_NOBANNER=
```
* `DOTDROP_DEBUG`: `-V --verbose`
* `DOTDROP_DEBUG`: `-V`/`--verbose`
```bash
export DOTDROP_DEBUG=
```
* `DOTDROP_FORCE_NODEBUG`: disable debug outputs even if `-V --verbose` is provided or `DOTDROP_DEBUG` is set
* `DOTDROP_FORCE_NODEBUG`: disable debug output even if `-V`/`--verbose` is provided or `DOTDROP_DEBUG` is set
```bash
export DOTDROP_FORCE_NODEBUG=
```
@@ -286,7 +282,7 @@ export DOTDROP_TMPDIR="/tmp/dotdrop-tmp"
```bash
export DOTDROP_WORKDIR="/tmp/dotdrop-workdir"
```
* `DOTDROP_WORKERS`: overwrite the `-w --workers` cli argument
* `DOTDROP_WORKERS`: overwrite the `-w`/`--workers` cli argument
```bash
export DOTDROP_WORKERS="10"
```
@@ -303,7 +299,7 @@ such as a cache.
Maybe you only want to change one file and don't want the others cluttering your repository.
Maybe the program changes these files quite often and creates unnecessary diffs in your dotfiles.
In these cases, you can use the [ingore-missing](config-format.md) option.
In these cases, you can use the [ignore-missing](config-format.md) option.
This option is available as a flag (`--ignore-missing` or `-z`) to the `update` and `compare` commands,
or [as a configuration option either globally or on a specific dotfile](config-format.md).