dotdrop/docs/usage.md

# Usage

Run `dotdrop --help` to see all available options.

## Basic usage

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 (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 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)

## Profile

The default profile used by dotdrop is the *hostname* of the host you are running dotdrop on.

It can be changed:

* 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 whether to dereference symlinks on import unless `-f`/`--force` is used.

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 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:

* `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:

* `d_colors` and `d_vim_colors` in the short format
* `d_mutt_colors` and `d_vim_colors` in the long format

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
dotfile management.
```bash
$ dotdrop import ~/.zshrc --as=~/.zshrc.test
```

To ignore specific patterns during import, see [the ignore patterns](config.md#ignore-patterns).

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
```

A dotfile will be installed only if it differs from the version already present at its destination.

Some available options:

* `-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
* `-W`/`--workdir-clear`: Clear the `workdir` before installing dotfiles (see config entry `clear_workdir`)

To ignore specific patterns 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 at their destinations with the ones stored in your `dotpath`.
```bash
$ dotdrop compare
```

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`.

You can specify against which destination file to compare:
```bash
$ dotdrop compare -C ~/.vimrc
```

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).

For more options, see the usage with `dotdrop --help`.

## List profiles

The `profiles` command lists the profiles defined in the config file.
```bash
$ dotdrop profiles
```

Dotdrop allows you to choose which profile to use
with the `--profile` switch if you use something
other than the default (the hostname).

The default profile can also be changed by defining the
`DOTDROP_PROFILE` environment variable.

## List dotfiles

The `files` command lists the dotfiles declared for a specific profile.
```bash
$ 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 [templating](templating.md) are listed.

It is also possible to list all the files related to each dotfile entry
by invoking the `detail` command, for example:
```bash
$ dotdrop detail
dotfiles details for profile "some-profile":
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 it contains
(does a specific file uses templating, etc.).

For more options, see the usage with `dotdrop --help`.

## Update dotfiles

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.

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
$ dotdrop update ~/.vimrc

## update by key with the --key switch
$ dotdrop update --key f_vimrc
```

If not argument is provided, all dotfiles for the selected profile are updated.

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).

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
`diff` can be used to view the changes.

```bash
$ dotdrop update ~/.vimrc
$ git diff
```

### The dotfile uses [templating](templating.md)

The dotfile must be manually updated; three solutions can be used to identify the
changes to apply to the template:

* Use the `compare` command:
```bash
## use compare to identify change(s)
$ dotdrop compare --file=~/.vimrc
```

* 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
[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"
```

* 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 -t f_vimrc
Installed to tmp /tmp/dotdrop-6ajz7565
$ diff ~/.vimrc /tmp/dotdrop-6ajz7565/home/user/.vimrc
```

## Remove dotfiles

The command `remove` allows you to stop managing a specific dotfile with
dotdrop. It will:

* 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`.

## Concurrency

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:

* `install`
* `compare`
* `update`

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 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 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

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`
```bash
export DOTDROP_PROFILE="my-fancy-profile"
```
* `DOTDROP_CONFIG`: `-c`/`--cfg`
```bash
export DOTDROP_CONFIG="/home/user/dotdrop/config.yaml"
```
* `DOTDROP_NOBANNER`: `-b`/`--no-banner`
```bash
export DOTDROP_NOBANNER=
```
* `DOTDROP_DEBUG`: `-V`/`--verbose`
```bash
export DOTDROP_DEBUG=
```
* `DOTDROP_FORCE_NODEBUG`: disable debug output even if `-V`/`--verbose` is provided or `DOTDROP_DEBUG` is set
```bash
export DOTDROP_FORCE_NODEBUG=
```
* `DOTDROP_TMPDIR`: defines a temporary directory for dotdrop to use for its operations instead of using a system generated one
```bash
export DOTDROP_TMPDIR="/tmp/dotdrop-tmp"
```
* `DOTDROP_WORKDIR`: overwrite the `workdir` defined in the config
```bash
export DOTDROP_WORKDIR="/tmp/dotdrop-workdir"
```
* `DOTDROP_WORKERS`: overwrite the `-w`/`--workers` cli argument
```bash
export DOTDROP_WORKERS="10"
```

## Ignore missing

Sometimes, it is nice to have [`update`](#update-dotfiles) not copy all the files in the installed directory
or [`compare`](#compare-dotfiles) diff them.

For example,
maybe you only want to include a single configuration file in your repository
and don't want to include other files the program uses,
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 [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).

To configure globally, place the following in `config.yaml`:
```yaml
config:
  ignore_missing_in_dotdrop: true
```

To configure per dotfile:
```yaml
dotfiles:
  f_abc:
    ignore_missing_in_dotdrop: true
```