Package: dotbot
DotbotDotbot makes installing your dotfiles as easy asgit clone $url && cd dotfiles && ./install, even on a freshly installed system!RationaleGetting StartedConfigurationDirectives(Link,Create,Shell,Clean,Defaults)PluginsCommand-line ArgumentsWikiRationaleDotbot is a tool that bootstraps your dotfiles (it's a [Dot]files
[bo]o[t]strapper, get it?). It doeslessthan 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.Seethis blog
postor more
resources on thetutorials
pagefor more detailed
explanations of how to organize your dotfiles.Getting StartedStarting Fresh?Great! You can automate the creation of your dotfiles by using the
user-contributedinit-dotfilesscript. If you'd rather use a
template repository, check outdotfiles_template. Or, if
you're just looking forsome inspiration, we've got you covered.Integrate with Existing DotfilesThe following will help you get set up using Dotbot in just a few steps.If you're usingGit, you can add Dotbot as a submodule:cd~/.dotfiles# replace with the path to your dotfilesgitinit# initialize repository if neededgitsubmoduleaddhttps://github.com/anishathalye/dotbot
gitconfig-f.gitmodulessubmodule.dotbot.ignoredirty# ignore dirty commits in the submodulecpdotbot/tools/git-submodule/install.
touchinstall.conf.yamlIf you're usingMercurial, you can add Dotbot as a subrepo:cd~/.dotfiles# replace with the path to your dotfileshginit# initialize repository if neededecho"dotbot = [git]https://github.com/anishathalye/dotbot">.hgsub
hgadd.hgsub
gitclonehttps://github.com/anishathalye/dotbot
cpdotbot/tools/hg-subrepo/install.
touchinstall.conf.yamlIf you are using PowerShell instead of a POSIX shell, you can use the providedinstall.ps1script instead ofinstall. On Windows, Dotbot only supports
Python 3.8+, and it requires that your account isallowed to create symbolic
links.To get started, you just need to fill in theinstall.conf.yamland Dotbot
will take care of the rest. To help you get started we havean
exampleconfig file as well asconfiguration
documentationfor the accepted parameters.Note: Theinstallscript 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 ininstall.conf.yamlthe Dotbot
submodule is located indotbot. You can change either of these parameters by
editing the variables in theinstallscript 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, rungit submodule update --remote dotbot, substitutingdotbotwith 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, rungit fetch && git checkout origin/masterin the Dotbot directory.If you prefer, you can install Dotbot fromPyPIand call it as a command-line
program:pipinstalldotbot
touchinstall.conf.yamlIn this case, rather than running./install, you can invoke Dotbot withdotbot -c <path to configuration file>.Full ExampleHere's an example of a complete configuration.The conventional name for the configuration file isinstall.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 asubset of YAML). JSON configuration files are
conventionally namedinstall.conf.json.ConfigurationDotbot uses YAML or JSON-formatted configuration files to let you specify how
to set up your dotfiles. Currently, Dotbot knows how tolinkfiles and
folders,createfolders, executeshellcommands, andcleandirectories of broken symbolic links. Dotbot also supports userpluginsfor 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 theequivalent JSONand check that it is correct.DirectivesMost Dotbot commands support both a simplified and extended syntax, and they
can also be configured via settingdefaults.LinkLink 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.FormatLink 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 notinclude 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.ParameterExplanationpathThe source for the symlink, the same as in the shortcut syntax (default: null, automatic (see below))createWhen true, create parent directories to the link as needed. (default: false)relinkRemoves the old target if it's a symlink (default: false)forceForce removes the old target, file or folder, and forces a new link (default: false)relativeUse a relative path to the source when creating the symlink (default: false, absolute links)canonicalizeResolve any symbolic links encountered in the source to symlink to the canonical path (default: true, real paths)ifExecute this in your$SHELLand only link if it is successful.ignore-missingDo not fail if the source is missing and create the link anyway (default: false)globTreatpathas a glob pattern, expanding patterns referenced below, linking allfilesmatched. (default: false)excludeArray of glob patterns to remove from glob matches. Uses same syntax aspath. Ignored ifglobisfalse. (default: empty, keep all matches)prefixPrepend prefix prefix to basename of each file when linked, whenglobistrue. (default: '')Whenglob: True, Dotbot usesglob.globto resolve glob paths, expanding Unix shell-style wildcards, which arenotthe same as regular expressions; Only the following are expanded:PatternMeaning*matches anything**matches anyfile, recursively?matches any single character[seq]matches any character inseq[!seq]matches any character not inseqHowever, due to the design ofglob.glob, using a glob pattern such asconfig/*, willnotmatch items that begin with.. To specifically capture items that being with., you will need to include the.in the pattern, like this:config/.*.When using glob with theexclude:option, the paths in the exclude paths should be relative to the base directory, same as the glob pattern itself. For example, if a glob patternvim/*matches directoriesvim/autoload,vim/ftdetect,vim/ftplugin, andvim/spell, and you want to ignore the spell directory, then you should useexclude: ["vim/spell"](not just"spell").Example-link:~/.config/terminator:create:truepath:config/terminator~/.vim:vim~/.vimrc:relink:truepath:vimrc~/.zshrc:force:truepath:zshrc~/.hammerspoon:if:'[`uname`=Darwin]'path:hammerspoon~/.config/:path:dotconf/config/**~/:glob:truepath:dotconf/*prefix:'.'If the source location is omitted or set tonull, 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:truepath:vimrc~/.zshrc:force:truepath:zshrc~/.config/:glob:truepath:config/*relink:trueexclude:[config/Code]~/.config/Code/User/:create:trueglob:truepath:config/Code/User/*relink:trueImplicit sources:-link:~/bin/ack:~/.vim:~/.vimrc:relink:true~/.zshrc:force:true~/.config/:glob:truepath:config/*relink:trueexclude:[config/Code]~/.config/Code/User/:create:trueglob:truepath:config/Code/User/*relink:trueCreateCreate 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.FormatCreate commands are specified as an array of directories to be created. If you
want to use the optional extended configuration, create commands are specified
as dictionaries. For convenience, it's permissible to leave the options blank
(null) in the dictionary syntax.ParameterExplanationmodeThe file mode to use for creating the leaf directory (default: 0777)Themodeparameter is treated in the same way as in Python'sos.mkdir. Its
behavior is platform-dependent. On Unix systems, the current umask value is
first masked out.Example-create:-~/downloads-~/.vim/undo-history-create:~/.ssh:mode:0700~/projects:ShellShell commands specify shell commands to be run. Shell commands are run in the
base directory (that is specified when running the installer).FormatShell 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.ParameterExplanationcommandThe command to be rundescriptionA human-readable message describing the command (default: null)quietShow only the description but not the command in log output (default: false)stdinAllow a command to read from standard input (default: false)stdoutShow a command's output from stdout (default: false)stderrShow a command's error output from stderr (default: false)Note thatquietcontrols 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 bystdout/stderr). When a command'sstdin/stdout/stderris 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 $varstdin:truestdout:truedescription:Reading and printing variablequiet:true-command:read failstderr:trueCleanClean 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 theforceoption is set totrue.FormatClean commands are specified as an array of directories to be cleaned.Clean commands also support an extended configuration syntax.ParameterExplanationforceRemove dead links even if they don't point to a file inside the dotfiles directory (default: false)recursiveTraverse the directory recursively looking for dead links (default: false)Note: using therecursiveoption for~is not recommended because it will
be slow.Example-clean:['~']-clean:~/:force:true~/.config:recursive:trueDefaultsDefault 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.FormatDefaults are specified as a dictionary mapping action names to settings, which
are dictionaries from option names to values.Example-defaults:link:create:truerelink:truePluginsDotbot also supports custom directives implemented by plugins. Plugins are
implemented as subclasses ofdotbot.Plugin, so they must implementcan_handle()andhandle(). Thecan_handle()method should returnTrueif the plugin can handle an action with the given name. Thehandle()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--pluginand--plugin-diroptions, using
either absolute paths or paths relative to the base directory. It is
recommended that these options are added directly to theinstallscript.Seeherefor a current list of plugins.Command-line ArgumentsDotbot 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.--onlyYou can call./install --only [list of directives], such as./install --only link, and Dotbot will only run those sections of the config file.--exceptYou 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.WikiCheck out theDotbot wikifor more information, tips and tricks,
user-contributed plugins, and more.ContributingDo you have a feature request, bug report, or patch? Great! SeeCONTRIBUTING.mdfor information on what you can do about that.LicenseCopyright (c) Anish Athalye. Released under the MIT License. SeeLICENSE.mdfor details.