14 KiB
Dotbot 
Dotbot makes installing your dotfiles as easy as git clone $url && cd dotfiles && ./install, even on a freshly installed system!
- Rationale
- Getting Started
- Configuration
- Directives (Link, Create, Shell, Clean, Defaults)
- Plugins
- Command-line Arguments
- Wiki
Rationale
Dotbot is a tool that bootstraps your dotfiles (it's a [Dot]files [bo]o[t]strapper, get it?). It does less than you think, because version control systems do more than you think.
Dotbot is designed to be lightweight and self-contained, with no external dependencies and no installation required. Dotbot can also be a drop-in replacement for any other tool you were using to manage your dotfiles, and Dotbot is VCS-agnostic -- it doesn't make any attempt to manage your dotfiles.
If you want an in-depth tutorial about organizing your dotfiles, see this blog post.
Getting Started
Starting Fresh?
Great! You can automate the creation of your dotfiles by using the user-contributed init-dotfiles script. If you'd rather use a template repository, check out dotfiles_template. Or, if you're just looking for some inspiration, we've got you covered.
Integrate with Existing Dotfiles
The following will help you get set up using Dotbot in just a few steps.
If you're using Git, you can add Dotbot as a submodule:
cd ~/.dotfiles # replace with the path to your dotfiles
git init # initialize repository if needed
git submodule add https://github.com/anishathalye/dotbot
git config -f .gitmodules submodule.dotbot.ignore dirty # ignore dirty commits in the submodule
cp dotbot/tools/git-submodule/install .
git add --chmod +x install
touch install.conf.yaml
If you're using Mercurial, you can add Dotbot as a subrepo:
cd ~/.dotfiles # replace with the path to your dotfiles
hg init # initialize repository if needed
echo "dotbot = [git]https://github.com/anishathalye/dotbot" > .hgsub
hg add .hgsub
git clone https://github.com/anishathalye/dotbot
cp dotbot/tools/hg-subrepo/install .
touch install.conf.yaml
To get started, you just need to fill in the install.conf.yaml and Dotbot
will take care of the rest. To help you get started we have an
example config file as well as configuration
documentation for the accepted parameters.
Note: The install script is merely a shim that checks out the appropriate
version of Dotbot and calls the full Dotbot installer. By default, the script
assumes that the configuration is located in install.conf.yaml the Dotbot
submodule is located in dotbot. You can change either of these parameters by
editing the variables in the install script appropriately.
Setting up Dotbot as a submodule or subrepo locks it on the current version.
You can upgrade Dotbot at any point. If using a submodule, run git submodule update --remote dotbot, substituting dotbot with the path to the Dotbot
submodule; be sure to commit your changes before running ./install, otherwise
the old version of Dotbot will be checked out by the install script. If using a
subrepo, run git fetch && git checkout origin/master in the Dotbot directory.
If you prefer, you can install Dotbot from PyPI and call it as a command-line program:
pip install dotbot
touch install.conf.yaml
In this case, rather than running ./install, you can invoke Dotbot with
dotbot -c <path to configuration file>.
Full Example
Here's an example of a complete configuration.
The conventional name for the configuration file is install.conf.yaml.
- defaults:
link:
relink: true
- clean: ['~']
- link:
~/.tmux.conf: tmux.conf
~/.vim: vim
~/.vimrc: vimrc
- create:
- ~/downloads
- ~/.vim/undo-history
- shell:
- [git submodule update --init --recursive, Installing submodules]
The configuration file is typically written in YAML, but it can also be written
in JSON (which is a subset of YAML). JSON configuration files are
conventionally named install.conf.json.
Configuration
Dotbot uses YAML or JSON-formatted configuration files to let you specify how to set up your dotfiles. Currently, Dotbot knows how to link files and folders, create folders, execute shell commands, and clean directories of broken symbolic links. Dotbot also supports user plugins for custom commands.
Ideally, bootstrap configurations should be idempotent. That is, the installer should be able to be run multiple times without causing any problems. This makes a lot of things easier to do (in particular, syncing updates between machines becomes really easy).
Dotbot configuration files are arrays of tasks, where each task is a dictionary that contains a command name mapping to data for that command. Tasks are run in the order in which they are specified. Commands within a task do not have a defined ordering.
When writing nested constructs, keep in mind that YAML is whitespace-sensitive. Following the formatting used in the examples is a good idea. If a YAML configuration file is not behaving as you expect, try inspecting the equivalent JSON and check that it is correct.
Directives
Most Dotbot commands support both a simplified and extended syntax, and they can also be configured via setting defaults.
Link
Link commands specify how files and directories should be symbolically linked. If desired, items can be specified to be forcibly linked, overwriting existing files if necessary. Environment variables in paths are automatically expanded.
Format
Link commands are specified as a dictionary mapping targets to source locations. Source locations are specified relative to the base directory (that is specified when running the installer). If linking directories, do not include a trailing slash.
Link commands support an optional extended configuration. In this type of configuration, instead of specifying source locations directly, targets are mapped to extended configuration dictionaries.
| Parameter | Explanation |
|---|---|
path |
The source for the symlink, the same as in the shortcut syntax (default: null, automatic (see below)) |
create |
When true, create parent directories to the link as needed. (default: false) |
relink |
Removes the old target if it's a symlink (default: false) |
force |
Force removes the old target, file or folder, and forces a new link (default: false) |
relative |
Use a relative path to the source when creating the symlink (default: false, absolute links) |
canonicalize-path |
Resolve any symbolic links encountered in the source to symlink to the canonical path (default: true, real paths) |
glob |
Treat a * character as a wildcard, and perform link operations on all of those matches (default: false) |
if |
Execute this in your $SHELL and only link if it is successful. |
ignore-missing |
Do not fail if the source is missing and create the link anyway (default: false) |
Example
- link:
~/.config/terminator:
create: true
path: config/terminator
~/.vim: vim
~/.vimrc:
relink: true
path: vimrc
~/.zshrc:
force: true
path: zshrc
~/.hammerspoon:
if: '[ `uname` = Darwin ]'
path: hammerspoon
If the source location is omitted or set to null, Dotbot will use the
basename of the destination, with a leading . stripped if present. This makes
the following two config files equivalent.
Explicit sources:
- link:
~/bin/ack: ack
~/.vim: vim
~/.vimrc:
relink: true
path: vimrc
~/.zshrc:
force: true
path: zshrc
~/.config/:
glob: true
path: config/*
relink: true
Implicit sources:
- link:
~/bin/ack:
~/.vim:
~/.vimrc:
relink: true
~/.zshrc:
force: true
~/.config/:
glob: true
path: config/*
relink: true
Create
Create commands specify empty directories to be created. This can be useful for scaffolding out folders or parent folder structure required for various apps, plugins, shell commands, etc.
Format
Create commands are specified as an array of directories to be created.
Example
- create:
- ~/projects
- ~/downloads
- ~/.vim/undo-history
Shell
Shell commands specify shell commands to be run. Shell commands are run in the base directory (that is specified when running the installer).
Format
Shell commands can be specified in several different ways. The simplest way is just to specify a command as a string containing the command to be run.
Another way is to specify a two element array where the first element is the shell command and the second is an optional human-readable description.
Shell commands support an extended syntax as well, which provides more fine-grained control.
| Parameter | Explanation |
|---|---|
command |
The command to be run |
description |
A human-readable message describing the command (default: null) |
quiet |
Show only the description but not the command in log output (default: false) |
stdin |
Allow a command to read from standard input (default: false) |
stdout |
Show a command's output from stdout (default: false) |
stderr |
Show a command's error output from stderr (default: false) |
Note that quiet controls whether the command (a string) is printed in log
output, it does not control whether the output from running the command is
printed (that is controlled by stdout / stderr). When a command's stdin /
stdout / stderr is not enabled (which is the default), it's connected to
/dev/null, disabling input and hiding output.
Example
- shell:
- chsh -s $(which zsh)
- [chsh -s $(which zsh), Making zsh the default shell]
-
command: read var && echo Your variable is $var
stdin: true
stdout: true
description: Reading and printing variable
quiet: true
-
command: read fail
stderr: true
Clean
Clean commands specify directories that should be checked for dead symbolic
links. These dead links are removed automatically. Only dead links that point
to somewhere within the dotfiles directory are removed unless the force
option is set to true.
Format
Clean commands are specified as an array of directories to be cleaned.
Clean commands also support an extended configuration syntax.
| Parameter | Explanation |
|---|---|
force |
Remove dead links even if they don't point to a file inside the dotfiles directory (default: false) |
recursive |
Traverse the directory recursively looking for dead links (default: false) |
Note: using the recursive option for ~ is not recommended because it will
be slow.
Example
- clean: ['~']
- clean:
~/:
force: true
~/.config:
recursive: true
Defaults
Default options for plugins can be specified so that options don't have to be repeated many times. This can be very useful to use with the link command, for example.
Defaults apply to all commands that come after setting the defaults. Defaults can be set multiple times; each change replaces the defaults with a new set of options.
Format
Defaults are specified as a dictionary mapping action names to settings, which are dictionaries from option names to values.
Example
- defaults:
link:
create: true
relink: true
Plugins
Dotbot also supports custom directives implemented by plugins. Plugins are
implemented as subclasses of dotbot.Plugin, so they must implement
can_handle() and handle(). The can_handle() method should return True
if the plugin can handle an action with the given name. The handle() method
should do something and return whether or not it completed successfully.
All built-in Dotbot directives are written as plugins that are loaded by default, so those can be used as a reference when writing custom plugins.
Plugins are loaded using the --plugin and --plugin-dir options, using
either absolute paths or paths relative to the base directory. It is
recommended that these options are added directly to the install script.
See here for a current list of plugins.
Command-line Arguments
Dotbot takes a number of command-line arguments; you can run Dotbot with
--help, e.g. by running ./install --help, to see the full list of options.
Here, we highlight a couple that are particularly interesting.
--only
You can call ./install --only [list of directives], such as ./install --only link, and Dotbot will only run those sections of the config file.
--except
You can call ./install --except [list of directives], such as ./install --except shell, and Dotbot will run all the sections of the config file except
the ones listed.
Wiki
Check out the Dotbot wiki for more information, tips and tricks, user-contributed plugins, and more.
Contributing
Do you have a feature request, bug report, or patch? Great! See CONTRIBUTING.md for information on what you can do about that.
Packaging
-
Update version information.
-
Build the package using
python setup.py sdist bdist_wheel. -
Sign and upload the package using
twine upload -s dist/*.
License
Copyright (c) 2014-2020 Anish Athalye. Released under the MIT License. See LICENSE.md for details.