1 # Dotbot [![Build Status](https://github.com/anishathalye/dotbot/workflows/CI/badge.svg)](https://github.com/anishathalye/dotbot/actions?query=workflow%3ACI)
3 Dotbot makes installing your dotfiles as easy as `git clone $url && cd dotfiles
4 && ./install`, even on a freshly installed system!
6 - [Rationale](#rationale)
7 - [Getting Started](#getting-started)
8 - [Configuration](#configuration)
9 - [Directives](#directives) ([Link](#link), [Create](#create), [Shell](#shell), [Clean](#clean), [Defaults](#defaults))
11 - [Command-line Arguments](#command-line-arguments)
18 Dotbot is a tool that bootstraps your dotfiles (it's a [Dot]files
19 [bo]o[t]strapper, get it?). It does *less* than you think, because version
20 control systems do more than you think.
22 Dotbot is designed to be lightweight and self-contained, with no external
23 dependencies and no installation required. Dotbot can also be a drop-in
24 replacement for any other tool you were using to manage your dotfiles, and
25 Dotbot is VCS-agnostic -- it doesn't make any attempt to manage your dotfiles.
28 post](https://www.anishathalye.com/2014/08/03/managing-your-dotfiles/) or more
29 resources on the [tutorials
30 page](https://github.com/anishathalye/dotbot/wiki/Tutorials) for more detailed
31 explanations of how to organize your dotfiles.
37 Great! You can automate the creation of your dotfiles by using the
38 user-contributed [init-dotfiles][init-dotfiles] script. If you'd rather use a
39 template repository, check out [dotfiles_template][dotfiles-template]. Or, if
40 you're just looking for [some inspiration][inspiration], we've got you covered.
42 ### Integrate with Existing Dotfiles
44 The following will help you get set up using Dotbot in just a few steps.
46 If you're using **Git**, you can add Dotbot as a submodule:
49 cd ~/.dotfiles # replace with the path to your dotfiles
50 git init # initialize repository if needed
51 git submodule add https://github.com/anishathalye/dotbot
52 git config -f .gitmodules submodule.dotbot.ignore dirty # ignore dirty commits in the submodule
53 cp dotbot/tools/git-submodule/install .
54 touch install.conf.yaml
57 If you're using **Mercurial**, you can add Dotbot as a subrepo:
60 cd ~/.dotfiles # replace with the path to your dotfiles
61 hg init # initialize repository if needed
62 echo "dotbot = [git]https://github.com/anishathalye/dotbot" > .hgsub
64 git clone https://github.com/anishathalye/dotbot
65 cp dotbot/tools/hg-subrepo/install .
66 touch install.conf.yaml
69 If you are using PowerShell instead of a POSIX shell, you can use the provided
70 `install.ps1` script instead of `install`. On Windows, Dotbot only supports
71 Python 3.8+, and it requires that your account is [allowed to create symbolic
72 links][windows-symlinks].
74 To get started, you just need to fill in the `install.conf.yaml` and Dotbot
75 will take care of the rest. To help you get started we have [an
76 example](#full-example) config file as well as [configuration
77 documentation](#configuration) for the accepted parameters.
79 Note: The `install` script is merely a shim that checks out the appropriate
80 version of Dotbot and calls the full Dotbot installer. By default, the script
81 assumes that the configuration is located in `install.conf.yaml` the Dotbot
82 submodule is located in `dotbot`. You can change either of these parameters by
83 editing the variables in the `install` script appropriately.
85 Setting up Dotbot as a submodule or subrepo locks it on the current version.
86 You can upgrade Dotbot at any point. If using a submodule, run `git submodule
87 update --remote dotbot`, substituting `dotbot` with the path to the Dotbot
88 submodule; be sure to commit your changes before running `./install`, otherwise
89 the old version of Dotbot will be checked out by the install script. If using a
90 subrepo, run `git fetch && git checkout origin/master` in the Dotbot directory.
92 If you prefer, you can install Dotbot from [PyPI] and call it as a command-line
97 touch install.conf.yaml
100 In this case, rather than running `./install`, you can invoke Dotbot with
101 `dotbot -c <path to configuration file>`.
105 Here's an example of a complete configuration.
107 The conventional name for the configuration file is `install.conf.yaml`.
117 ~/.tmux.conf: tmux.conf
123 - ~/.vim/undo-history
126 - [git submodule update --init --recursive, Installing submodules]
129 The configuration file is typically written in YAML, but it can also be written
130 in JSON (which is a [subset of YAML][json2yaml]). JSON configuration files are
131 conventionally named `install.conf.json`.
135 Dotbot uses YAML or JSON-formatted configuration files to let you specify how
136 to set up your dotfiles. Currently, Dotbot knows how to [link](#link) files and
137 folders, [create](#create) folders, execute [shell](#shell) commands, and
138 [clean](#clean) directories of broken symbolic links. Dotbot also supports user
139 [plugins](#plugins) for custom commands.
141 **Ideally, bootstrap configurations should be idempotent. That is, the
142 installer should be able to be run multiple times without causing any
143 problems.** This makes a lot of things easier to do (in particular, syncing
144 updates between machines becomes really easy).
146 Dotbot configuration files are arrays of tasks, where each task
147 is a dictionary that contains a command name mapping to data for that command.
148 Tasks are run in the order in which they are specified. Commands within a task
149 do not have a defined ordering.
151 When writing nested constructs, keep in mind that YAML is whitespace-sensitive.
152 Following the formatting used in the examples is a good idea. If a YAML
153 configuration file is not behaving as you expect, try inspecting the
154 [equivalent JSON][json2yaml] and check that it is correct.
158 Most Dotbot commands support both a simplified and extended syntax, and they
159 can also be configured via setting [defaults](#defaults).
163 Link commands specify how files and directories should be symbolically linked.
164 If desired, items can be specified to be forcibly linked, overwriting existing
165 files if necessary. Environment variables in paths are automatically expanded.
169 Link commands are specified as a dictionary mapping targets to source
170 locations. Source locations are specified relative to the base directory (that
171 is specified when running the installer). If linking directories, *do not*
172 include a trailing slash.
174 Link commands support an optional extended configuration. In this type of
175 configuration, instead of specifying source locations directly, targets are
176 mapped to extended configuration dictionaries.
178 | Parameter | Explanation |
180 | `path` | The source for the symlink, the same as in the shortcut syntax (default: null, automatic (see below)) |
181 | `create` | When true, create parent directories to the link as needed. (default: false) |
182 | `relink` | Removes the old target if it's a symlink (default: false) |
183 | `force` | Force removes the old target, file or folder, and forces a new link (default: false) |
184 | `relative` | Use a relative path to the source when creating the symlink (default: false, absolute links) |
185 | `canonicalize` | Resolve any symbolic links encountered in the source to symlink to the canonical path (default: true, real paths) |
186 | `if` | Execute this in your `$SHELL` and only link if it is successful. |
187 | `ignore-missing` | Do not fail if the source is missing and create the link anyway (default: false) |
188 | `glob` | Treat `path` as a glob pattern, expanding patterns referenced below, linking all *files* matched. (default: false) |
189 | `exclude` | Array of glob patterns to remove from glob matches. Uses same syntax as `path`. Ignored if `glob` is `false`. (default: empty, keep all matches) |
190 | `prefix` | Prepend prefix prefix to basename of each file when linked, when `glob` is `true`. (default: '') |
192 When `glob: True`, Dotbot uses [glob.glob](https://docs.python.org/3/library/glob.html#glob.glob) to resolve glob paths, expanding Unix shell-style wildcards, which are **not** the same as regular expressions; Only the following are expanded:
194 | Pattern | Meaning |
195 |:---------|:-------------------------------------------------------|
196 | `*` | matches anything |
197 | `**` | matches any **file**, recursively (Python >= 3.5 only) |
198 | `?` | matches any single character |
199 | `[seq]` | matches any character in `seq` |
200 | `[!seq]` | matches any character not in `seq` |
202 However, due to the design of `glob.glob`, using a glob pattern such as `config/*`, will **not** match items that begin with `.`. To specifically capture items that being with `.`, you will need to include the `.` in the pattern, like this: `config/.*`.
208 ~/.config/terminator:
210 path: config/terminator
219 if: '[ `uname` = Darwin ]'
222 path: dotconf/config/**
229 If the source location is omitted or set to `null`, Dotbot will use the
230 basename of the destination, with a leading `.` stripped if present. This makes
231 the following two config files equivalent.
249 exclude: [ config/Code ]
250 ~/.config/Code/User/:
253 path: config/Code/User/*
271 exclude: [ config/Code ]
272 ~/.config/Code/User/:
275 path: config/Code/User/*
281 Create commands specify empty directories to be created. This can be useful
282 for scaffolding out folders or parent folder structure required for various
283 apps, plugins, shell commands, etc.
287 Create commands are specified as an array of directories to be created. If you
288 want to use the optional extended configuration, create commands are specified
289 as dictionaries. For convenience, it's permissible to leave the options blank
290 (null) in the dictionary syntax.
292 | Parameter | Explanation |
294 | `mode` | The file mode to use for creating the leaf directory (default: 0777) |
296 The `mode` parameter is treated in the same way as in Python's
297 [os.mkdir](https://docs.python.org/3/library/os.html#mkdir-modebits). Its
298 behavior is platform-dependent. On Unix systems, the current umask value is
306 - ~/.vim/undo-history
315 Shell commands specify shell commands to be run. Shell commands are run in the
316 base directory (that is specified when running the installer).
320 Shell commands can be specified in several different ways. The simplest way is
321 just to specify a command as a string containing the command to be run.
323 Another way is to specify a two element array where the first element is the
324 shell command and the second is an optional human-readable description.
326 Shell commands support an extended syntax as well, which provides more
327 fine-grained control.
329 | Parameter | Explanation |
331 | `command` | The command to be run |
332 | `description` | A human-readable message describing the command (default: null) |
333 | `quiet` | Show only the description but not the command in log output (default: false) |
334 | `stdin` | Allow a command to read from standard input (default: false) |
335 | `stdout` | Show a command's output from stdout (default: false) |
336 | `stderr` | Show a command's error output from stderr (default: false) |
338 Note that `quiet` controls whether the command (a string) is printed in log
339 output, it does not control whether the output from running the command is
340 printed (that is controlled by `stdout` / `stderr`). When a command's `stdin` /
341 `stdout` / `stderr` is not enabled (which is the default), it's connected to
342 `/dev/null`, disabling input and hiding output.
348 - chsh -s $(which zsh)
349 - [chsh -s $(which zsh), Making zsh the default shell]
351 command: read var && echo Your variable is $var
354 description: Reading and printing variable
363 Clean commands specify directories that should be checked for dead symbolic
364 links. These dead links are removed automatically. Only dead links that point
365 to somewhere within the dotfiles directory are removed unless the `force`
366 option is set to `true`.
370 Clean commands are specified as an array of directories to be cleaned.
372 Clean commands also support an extended configuration syntax.
374 | Parameter | Explanation |
376 | `force` | Remove dead links even if they don't point to a file inside the dotfiles directory (default: false) |
377 | `recursive` | Traverse the directory recursively looking for dead links (default: false) |
379 Note: using the `recursive` option for `~` is not recommended because it will
396 Default options for plugins can be specified so that options don't have to be
397 repeated many times. This can be very useful to use with the link command, for
400 Defaults apply to all commands that come after setting the defaults. Defaults
401 can be set multiple times; each change replaces the defaults with a new set of
406 Defaults are specified as a dictionary mapping action names to settings, which
407 are dictionaries from option names to values.
420 Dotbot also supports custom directives implemented by plugins. Plugins are
421 implemented as subclasses of `dotbot.Plugin`, so they must implement
422 `can_handle()` and `handle()`. The `can_handle()` method should return `True`
423 if the plugin can handle an action with the given name. The `handle()` method
424 should do something and return whether or not it completed successfully.
426 All built-in Dotbot directives are written as plugins that are loaded by
427 default, so those can be used as a reference when writing custom plugins.
429 Plugins are loaded using the `--plugin` and `--plugin-dir` options, using
430 either absolute paths or paths relative to the base directory. It is
431 recommended that these options are added directly to the `install` script.
433 See [here][plugins] for a current list of plugins.
435 ## Command-line Arguments
437 Dotbot takes a number of command-line arguments; you can run Dotbot with
438 `--help`, e.g. by running `./install --help`, to see the full list of options.
439 Here, we highlight a couple that are particularly interesting.
443 You can call `./install --only [list of directives]`, such as `./install --only
444 link`, and Dotbot will only run those sections of the config file.
448 You can call `./install --except [list of directives]`, such as `./install
449 --except shell`, and Dotbot will run all the sections of the config file except
454 Check out the [Dotbot wiki][wiki] for more information, tips and tricks,
455 user-contributed plugins, and more.
459 Do you have a feature request, bug report, or patch? Great! See
460 [CONTRIBUTING.md][contributing] for information on what you can do about that.
464 Copyright (c) 2014-2021 Anish Athalye. Released under the MIT License. See
465 [LICENSE.md][license] for details.
467 [PyPI]: https://pypi.org/project/dotbot/
468 [init-dotfiles]: https://github.com/Vaelatern/init-dotfiles
469 [dotfiles-template]: https://github.com/anishathalye/dotfiles_template
470 [inspiration]: https://github.com/anishathalye/dotbot/wiki/Users
471 [windows-symlinks]: https://learn.microsoft.com/en-us/windows/security/threat-protection/security-policy-settings/create-symbolic-links
472 [json2yaml]: https://www.json2yaml.com/
473 [plugins]: https://github.com/anishathalye/dotbot/wiki/Plugins
474 [wiki]: https://github.com/anishathalye/dotbot/wiki
475 [contributing]: CONTRIBUTING.md
476 [license]: LICENSE.md