4 Dotbot makes installing your dotfiles as easy as `git clone $url && cd dotfiles
5 && ./install`, even on a freshly installed system!
9 [![Build Status](https://travis-ci.org/anishathalye/dotbot.svg?branch=master)](https://travis-ci.org/anishathalye/dotbot)
11 Dotbot is a tool that bootstraps your dotfiles (it's a [Dot]files
12 [bo]o[t]strapper, get it?). It does *less* than you think, because version
13 control systems do more than you think.
15 Dotbot is designed to be lightweight and self-contained, with no external
16 dependencies and no installation required. Dotbot can also be a drop-in
17 replacement for any other tool you were using to manage your dotfiles, and
18 Dotbot is VCS-agnostic -- it doesn't make any attempt to manage your dotfiles.
20 If you want an in-depth tutorial about organizing your dotfiles, see this [blog
21 post][managing-dotfiles-post].
23 Get Running in 5 Minutes
24 ------------------------
28 Great! You can automate the creation of your dotfiles by using the
29 user-contributed [init-dotfiles][init-dotfiles] script. If you'd rather use a
30 template repository, check out [dotfiles_template][dotfiles-template]. Or, if
31 you're just looking for [some inspiration][inspiration], we've got you covered.
33 ### Integrate with Existing Dotfiles
35 The following will help you get set up using Dotbot in just a few steps.
37 If you're using **Git**, you can add Dotbot as a submodule:
40 cd ~/.dotfiles # replace with the path to your dotfiles
41 git init # initialize repository if needed
42 git submodule add https://github.com/anishathalye/dotbot
43 git config -f .gitmodules submodule.dotbot.ignore dirty # ignore dirty commits in the submodule
44 cp dotbot/tools/git-submodule/install .
45 touch install.conf.yaml
48 If you're using **Mercurial**, you can add Dotbot as a subrepo:
51 cd ~/.dotfiles # replace with the path to your dotfiles
52 hg init # initialize repository if needed
53 echo "dotbot = [git]https://github.com/anishathalye/dotbot" > .hgsub
55 git clone https://github.com/anishathalye/dotbot
56 cp dotbot/tools/hg-subrepo/install .
57 touch install.conf.yaml
60 To get started, you just need to fill in the `install.conf.yaml` and Dotbot
61 will take care of the rest. To help you get started we have [an
62 example](#full-example) config file as well as [configuration
63 documentation](#configuration) for the accepted parameters.
65 Note: The `install` script is merely a shim that checks out the appropriate
66 version of Dotbot and calls the full Dotbot installer. By default, the script
67 assumes that the configuration is located in `install.conf.yaml` the Dotbot
68 submodule is located in `dotbot`. You can change either of these parameters by
69 editing the variables in the `install` script appropriately.
71 Setting up Dotbot as a submodule or subrepo locks it on the current version.
72 You can upgrade Dotbot at any point. If using a submodule, run `git submodule
73 update --remote dotbot`, substituting `dotbot` with the path to the Dotbot
74 submodule; be sure to commit your changes before running `./install`, otherwise
75 the old version of Dotbot will be checked out by the install script. If using a
76 subrepo, run `git fetch && git checkout origin/master` in the Dotbot directory.
78 If you prefer, you can install Dotbot from [PyPI] and call it as a command-line
83 touch install.conf.yaml
86 In this case, rather than running `./install`, you can invoke Dotbot with
87 `dotbot -c <path to configuration file>`.
91 Here's an example of a complete configuration.
93 The conventional name for the configuration file is `install.conf.yaml`.
104 ~/.tmux.conf: tmux.conf
110 - ~/.vim/undo-history
113 - [git submodule update --init --recursive, Installing submodules]
116 The configuration file is typically written in YAML, but it can also be written
117 in JSON (which is a subset of YAML). [Here][json-equivalent] is the JSON
118 [equivalent][json2yaml] of the YAML configuration given above. JSON
119 configuration files are conventionally named `install.conf.json`.
124 Dotbot uses YAML or JSON-formatted configuration files to let you specify how
125 to set up your dotfiles. Currently, Dotbot knows how to [link](#link) files and
126 folders, [create](#create) folders, execute [shell](#shell) commands, and
127 [clean](#clean) directories of broken symbolic links. Dotbot also supports user
128 [plugins](#plugins) for custom commands.
130 **Ideally, bootstrap configurations should be idempotent. That is, the
131 installer should be able to be run multiple times without causing any
132 problems.** This makes a lot of things easier to do (in particular, syncing
133 updates between machines becomes really easy).
135 Dotbot configuration files are arrays of tasks, where each task
136 is a dictionary that contains a command name mapping to data for that command.
137 Tasks are run in the order in which they are specified. Commands within a task
138 do not have a defined ordering.
140 When writing nested constructs, keep in mind that YAML is whitespace-sensitive.
141 Following the formatting used in the examples is a good idea. If a YAML
142 configuration file is not behaving as you expect, try inspecting the
143 [equivalent JSON][json2yaml] and check that it is correct.
145 Also, note that `~` in YAML is the same as `null` in JSON. If you want a single
146 character string containing a tilde, make sure to enclose it in quotes: `'~'`
150 Link commands specify how files and directories should be symbolically linked.
151 If desired, items can be specified to be forcibly linked, overwriting existing
152 files if necessary. Environment variables in paths are automatically expanded.
156 Link commands are specified as a dictionary mapping targets to source
157 locations. Source locations are specified relative to the base directory (that
158 is specified when running the installer). If linking directories, *do not* include a trailing slash.
160 Link commands support an (optional) extended configuration. In this type of
161 configuration, instead of specifying source locations directly, targets are
162 mapped to extended configuration dictionaries.
164 Available extended configuration parameters:
166 | Link Option | Explanation |
168 | `path` | The source for the symlink, the same as in the shortcut syntax (default:null, automatic (see below)) |
169 | `create` | When true, create parent directories to the link as needed. (default:false) |
170 | `relink` | Removes the old target if it's a symlink (default:false) |
171 | `force` | Force removes the old target, file or folder, and forces a new link (default:false) |
172 | `relative` | Use a relative path to the source when creating the symlink (default:false, absolute links) |
173 | `glob` | Treat a `*` character as a wildcard, and perform link operations on all of those matches (default:false) |
174 | `if` | Execute this in your `$SHELL` and only link if it is successful. |
180 ~/.config/terminator:
182 path: config/terminator
192 If the source location is omitted or set to `null`, Dotbot will use the
193 basename of the destination, with a leading `.` stripped if present. This makes
194 the following config files equivalent:
228 Create commands specify empty directories to be created. This can be useful
229 for scaffolding out folders or parent folder structure required for various
230 apps, plugins, shell commands, etc.
234 Create commands are specified as an array of directories to be created.
242 - ~/.vim/undo-history
247 Shell commands specify shell commands to be run. Shell commands are run in the
248 base directory (that is specified when running the installer).
252 Shell commands can be specified in several different ways. The simplest way is
253 just to specify a command as a string containing the command to be run.
255 Another way is to specify a two element array where the first element is the
256 shell command and the second is an optional human-readable description.
258 Shell commands support an extended syntax as well, which provides more
259 fine-grained control. A command can be specified as a dictionary that contains
260 the command to be run, a description, whether to suppress outputting the
261 command in the display via `quiet`, and whether `stdin`, `stdout`,
262 and `stderr` are enabled. In this syntax, all keys are optional except for the
269 - chsh -s $(which zsh)
270 - [chsh -s $(which zsh), Making zsh the default shell]
272 command: read var && echo Your variable is $var
275 description: Reading and printing variable
284 Clean commands specify directories that should be checked for dead symbolic
285 links. These dead links are removed automatically. Only dead links that point
286 to the dotfiles directory are removed unless the `force` option is set to
291 Clean commands are specified as an array of directories to be cleaned.
293 Clean commands support an extended configuration syntax. In this type of
294 configuration, commands are specified as directory paths mapping to options. If
295 the `force` option is set to `true`, dead links are removed even if they don't
296 point to a file inside the dotfiles directory.
310 Default options for plugins can be specified so that options don't have to be
311 repeated many times. This can be very useful to use with the link command, for
314 Defaults apply to all commands that follow setting the defaults. Defaults can
315 be set multiple times; each change replaces the defaults with a new set of
320 Defaults are specified as a dictionary mapping action names to settings, which
321 are dictionaries from option names to values.
334 Dotbot also supports custom directives implemented by plugins. Plugins are
335 implemented as subclasses of `dotbot.Plugin`, so they must implement
336 `can_handle()` and `handle()`. The `can_handle()` method should return `True`
337 if the plugin can handle an action with the given name. The `handle()` method
338 should do something and return whether or not it completed successfully.
340 All built-in Dotbot directives are written as plugins that are loaded by
341 default, so those can be used as a reference when writing custom plugins.
343 Plugins are loaded using the `--plugin` and `--plugin-dir` options, using
344 either absolute paths or paths relative to the base directory. It is
345 recommended that these options are added directly to the `install` script.
350 Check out the [Dotbot wiki][wiki] for more information, tips and tricks,
351 user-contributed plugins, and more.
356 Do you have a feature request, bug report, or patch? Great! See
357 [CONTRIBUTING.md][contributing] for information on what you can do about that.
362 1. Update version information.
364 2. Build the package using ``python setup.py sdist bdist_wheel``.
366 3. Sign and upload the package using ``twine upload -s dist/*``.
371 Copyright (c) 2014-2019 Anish Athalye. Released under the MIT License. See
372 [LICENSE.md][license] for details.
374 [PyPI]: https://pypi.org/project/dotbot/
375 [init-dotfiles]: https://github.com/Vaelatern/init-dotfiles
376 [dotfiles-template]: https://github.com/anishathalye/dotfiles_template
377 [inspiration]: https://github.com/anishathalye/dotbot/wiki/Users
378 [managing-dotfiles-post]: http://www.anishathalye.com/2014/08/03/managing-your-dotfiles/
379 [json-equivalent]: https://gist.github.com/anishathalye/84bd6ba1dbe936e05141e07ec45f5fd4
380 [json2yaml]: https://www.json2yaml.com/
381 [wiki]: https://github.com/anishathalye/dotbot/wiki
382 [contributing]: CONTRIBUTING.md
383 [license]: LICENSE.md