dotdrop/docs/usage.md

Usage

Run dotdrop --help to see all available options.

• Basic use
• Commands:
  • Install dotfiles
  • Compare dotfiles
  • Import dotfiles
  • List profiles
  • List dotfiles
  • Update dotfiles
  • Remove dotfiles
• Uses
  • Use actions
  • Use transformations
• Update dotdrop
• Environment variables
• User tricks

---

Basic use

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 the dotpath of dotdrop.

For more advanced uses:

• See this wiki
• dotdrop --help for more options.
• the example

Install dotfiles

Simply run

$ dotdrop install

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 dedicated wiki page

Compare dotfiles

Compare local dotfiles with the ones stored in dotdrop:

$ 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 dedicated wiki page

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

Dotdrop allows to import dotfiles directly from the filesystem. It will copy the dotfile and update the config file automatically.

Note that dotdrop will dereference all symlinks when importing a file or directory (see issue #184 for more)

For example to import ~/.xinitrc

$ dotdrop import ~/.xinitrc

You can control how the dotfile key is generated in the config file with the option longkey (per default 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

Dotfile can be imported as a different file with the use of the command line switch --as. It is however recommended to use the templating to avoid duplicates and optimize dotfiles management.

$ dotdrop import ~/.zshrc --as=~/.zshrc.test

List profiles

$ dotdrop profiles

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

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

List dotfiles

The following command lists the different dotfiles configured for a specific profile:

$ 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

By using the -T --template switch, only the dotfiles that are using jinja2 directives are listed.

It is also possible to list all files related to each dotfile entries by invoking the detail command, for example:

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

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

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.

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.

# 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 pattern, see the dedicated wiki page

There are two cases when updating a dotfile:

The dotfile doesn't use templating

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.

$ dotdrop update ~/.vimrc
$ git diff

The dotfile uses templating

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

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

# use install to identify change(s)
$ dotdrop install -t
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.

$ dotdrop install -t f_zshrc

Remove dotfiles

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

• remove the entry in the config file (under dotfiles and profile)
• remove the file from the dotpath

Update dotdrop

If using dotdrop as a submodule, one can control if dotdrop is auto-updated through the dotdrop.sh script by defining the environment variable DOTDROP_AUTOUPDATE=yes. If undefined, DOTDROP_AUTOUPDATE will take the value yes.

If used as a submodule, update it with

$ git submodule update --init --recursive
$ git submodule update --remote dotdrop

You will then need to commit the changes with

$ git add dotdrop
$ git commit -m 'update dotdrop'
$ git push

Or if installed through pypi:

$ pip3 install --user dotdrop --upgrade

Environment variables

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

export DOTDROP_PROFILE="my-fancy-profile"

• DOTDROP_CONFIG: -c --cfg

export DOTDROP_CONFIG="/home/user/dotdrop/config.yaml"

• DOTDROP_NOBANNER: -b --no-banner

export DOTDROP_NOBANNER=

• DOTDROP_DEBUG: -V --verbose

export DOTDROP_DEBUG=

• DOTDROP_FORCE_NODEBUG: disable debug outputs even if -V --verbose is provided or DOTDROP_DEBUG is set

export DOTDROP_FORCE_NODEBUG=

User tricks

Improve git integration

The below aliases can help with the process of updating your dotfiles between multiple hosts. Add those to your ~/.zshrc or ~/.bashrc. You can then simply run dotsync to push or pull from your dotfile repository.

# Your dotdrop git repository location
export DOTREPO="/path/to/your/dotdrop/repo"

alias dotdrop="$DOTREPO/dotdrop.sh"
alias dotgit="git -C $DOTREPO"
alias dotsync="dotgit pull && dotgit add -A && dotgit commit && dotgit push; dotdrop install"

Provided by ReekyMarko