216 lines
6.5 KiB
Markdown
216 lines
6.5 KiB
Markdown
Dotbot
|
|
======
|
|
|
|
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][managing-dotfiles-post].
|
|
|
|
Get Running in 5 Minutes
|
|
---------------------------
|
|
|
|
### Starting Fresh?
|
|
|
|
Great! Just run the following command and start adding your customizations. If
|
|
you're looking for [some inpiration][inspiration], we've got you covered.
|
|
|
|
```bash
|
|
git clone git@github.com:anishathalye/dotfiles_template dotfiles
|
|
```
|
|
|
|
### Integrate with Existing Dotfiles
|
|
|
|
The following will help you get set up using Dotbot in just a few steps.
|
|
|
|
```bash
|
|
# replace with the path to your dotfiles
|
|
cd ~/.dotfiles
|
|
git submodule add https://github.com/anishathalye/dotbot
|
|
cp dotbot/tools/git-submodule/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](#full-example) config file as well as [configuration
|
|
documentation](#configuration) 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 appropiately.
|
|
|
|
|
|
### Full Example
|
|
|
|
Here's an example of a complete configuration.
|
|
|
|
The conventional name for the configuration file is `install.conf.yaml`.
|
|
|
|
```yaml
|
|
- clean: ['~']
|
|
|
|
- link:
|
|
~/.dotfiles: ''
|
|
~/.tmux.conf: tmux.conf
|
|
~/.vim: vim/
|
|
~/.vimrc: vimrc
|
|
|
|
- shell:
|
|
- [git submodule update --init --recursive, Installing submodules]
|
|
```
|
|
|
|
The configuration file can also be written in JSON. Here is the JSON equivalent
|
|
of the YAML configuration given above.
|
|
|
|
The conventional name for this file is `install.conf.json`.
|
|
|
|
```json
|
|
[
|
|
{
|
|
"clean": ["~"]
|
|
},
|
|
{
|
|
"link": {
|
|
"~/.dotfiles": "",
|
|
"~/.tmux.conf": "tmux.conf",
|
|
"~/.vim": "vim/",
|
|
"~/.vimrc": "vimrc"
|
|
}
|
|
},
|
|
{
|
|
"shell": [
|
|
["git submodule update --init --recursive", "Installing submodules"]
|
|
]
|
|
}
|
|
]
|
|
```
|
|
|
|
## 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](#link) files and
|
|
folders, execute [shell](#shell) commands, and [clean](#clean) directories of
|
|
broken symbolic links.
|
|
|
|
**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.
|
|
|
|
### 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.
|
|
|
|
#### 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). Source directory names should contain
|
|
a trailing "/" character.
|
|
|
|
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. These dictionaries map `path` to
|
|
the source path, specify `create` as `true` if the parent directory should be
|
|
created if necessary, and specify `force` as `true` if the file or directory
|
|
should be forcibly linked.
|
|
|
|
#### Example
|
|
|
|
```yaml
|
|
- link:
|
|
~/.config/terminator:
|
|
create: true
|
|
path: config/terminator/
|
|
~/.vim: vim/
|
|
~/.vimrc: vimrc
|
|
~/.zshrc:
|
|
force: true
|
|
path: zshrc
|
|
```
|
|
|
|
### 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. A command can be specified as a dictionary that contains
|
|
the command to be run, a description, and whether `stdin`, `stdout`, and
|
|
`stderr` are enabled. In this syntax, all keys are optional except for the
|
|
command itself.
|
|
|
|
#### Example
|
|
|
|
```yaml
|
|
- shell:
|
|
- mkdir -p ~/src
|
|
- [mkdir -p ~/downloads, Creating downloads directory]
|
|
-
|
|
command: read var && echo Your variable is $var
|
|
stdin: true
|
|
stdout: 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 the dotfiles directory are removed.
|
|
|
|
#### Format
|
|
|
|
Clean commands are specified as an array of directories to be cleaned.
|
|
|
|
#### Example
|
|
|
|
```yaml
|
|
- clean: ['~']
|
|
```
|
|
|
|
Contributing
|
|
------------
|
|
|
|
Do you have a feature request, bug report, or patch? Great! See
|
|
[CONTRIBUTING.md][contributing] for information on what you can do about that.
|
|
|
|
License
|
|
-------
|
|
|
|
Copyright (c) 2014-2015 Anish Athalye. Released under the MIT License. See
|
|
[LICENSE.md][license] for details.
|
|
|
|
[inspiration]: https://github.com/anishathalye/dotfiles_template#inspiration
|
|
[managing-dotfiles-post]: http://www.anishathalye.com/2014/08/03/managing-your-dotfiles/
|
|
[contributing]: CONTRIBUTING.md
|
|
[license]: LICENSE.md
|