diff --git a/README.md b/README.md index fb31abd..486fbd9 100644 --- a/README.md +++ b/README.md @@ -10,8 +10,8 @@ dependencies and no installation required. Dotbot is easy to set up, and it's easy to configure. Dotbot is VCS-agnostic, and it doesn't make any attempt to manage your -dotfiles. Existing version control systems like git are pretty awesome at -doing this. +dotfiles. Existing version control systems like git are pretty awesome at doing +this. Dotbot can be a drop-in replacement for any other tool you were using to manage your dotfiles. @@ -25,27 +25,23 @@ post][managing-dotfiles-post]. A great way to organize your dotfiles is having all of them in a single (isolated) git repository and symlinking files into place. You can add plugins and stuff using git submodules. This whole symlinking business can be a bit of -trouble, but it's much better than just having your entire home directory under -source control, and Dotbot lets you have a one-click install process, so you -can have all the benefits of isolation without the annoyance of having to -manually copy or link files. +work, but it's much better than just having your entire home directory under +source control, and Dotbot can automate all of this for you and let you have a +one-click install process, so you can have all the benefits of isolation +without the annoyance of having to manually copy or link files. -Dotbot itself is entirely self contained and requires no installation, so it's -not necessary to install any software before you provision a new machine! All -you have to do is download your dotfiles and then run `./install`. +Dotbot itself is entirely self contained and requires no installation (it's +self-bootstrapping), so it's not necessary to install any software before you +provision a new machine! All you have to do is download your dotfiles and then +run `./install`. Template -------- -To make life easier, you can fork the [template repository][template]. If you -want, you can rename it afterwards (to something like just `dotfiles`). If -you're looking for inspiration, the template repository contains links to -dotfiles repositories that use Dotbot. - -If you prefer, instead of reading about how Dotbot works, you could refer to -the code in the template repository and get a feel for how to set things up, -learning by example. - +If you are starting fresh with your dotfiles, you can fork the [template +repository][template]. If you want, you can rename it afterwards (to something +like just "dotfiles"). If you're looking for inspiration, the template +repository contains links to dotfiles repositories that use Dotbot. Setup ----- @@ -53,9 +49,12 @@ Setup Dotbot is super easy to set up. This description is given in terms of git and git submodules, but the procedure is similar for other VCSs. -You can add Dotbot to your dotfiles by running -`git submodule add https://github.com/anishathalye/dotbot` -from within your git repository. +You can add Dotbot to your dotfiles by running the following command from +within your git repository: + +```bash +git submodule add https://github.com/anishathalye/dotbot +``` To have a one-click (one-command) install, you can place a bootstrap install shell script that calls Dotbot with the appropriate parameters. This script @@ -63,7 +62,7 @@ simply passes its arguments to Dotbot, so the script itself will not have to be updated once it's placed in the proper location (the Dotbot repository can be updated independently). -An example bootstrap install shell script is given in +An bootstrap install shell script for git is given in [tools/git-submodule/install][git-install]. The script assumes that the configuration is located in `install.conf.json` and Dotbot is located in `dotbot`. The script automatically makes sure that the correct version of @@ -76,28 +75,85 @@ Configuration ------------- Dotbot uses json-formatted configuration files to let you specify how to set up -your dotfiles. Currently, Dotbot knows how to `link` files, execute `shell` -commands, and `clean` directories of broken symbolic links. Dotbot executes -tasks in the order that they are specified in. +your dotfiles. Currently, Dotbot knows how to `link` files and folders, execute +`shell` commands, and `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 life easier. +problems.** This makes a lot of things easier to do (in particular, syncing +updates between machines becomes really easy). Dotbot configuration files are json arrays of tasks, where each task is a -dictionary that contains a command name mapping to data for that command. For -`link`, you specify how files should be linked in a dictionary. For `shell`, -you specify an array consisting of commands, where each command is an array -consisting of the shell command as the first element and a description as the -second. For `clean`, you specify an array consisting of targets, where each -target is a path to a directory. +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. -Dotbot is aware of a base directory (that is specified when running the -installer), so link targets can be specified relative to that, and shell -commands will be run in the base directory. +### Link -The configuration format is pretty simple, so here's an example to help you get -started. The convention for configuration file names is `install.conf.json`. +Link commands specify how files and directories should be symbolically linked. + +#### 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. + +##### Example + +```json +{ + "link": { + "~/.vimrc": "vimrc", + "~/.vim": "vim/" + } +} +``` + +### 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 are specified as an array of commands, where each command is a +two element array containing the actual shell command as the first element and +a human-readable description as the second element. + +##### Example + +```json +{ + "shell": [ + ["mkdir -p ~/downloads", "Creating downloads directory"] + ] +} +``` + +### 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 + +```json +{ + "clean": ["~"] +} +``` + +### Full Example + +The configuration file format is pretty simple. Here's an example of a complete +configuration. The conventional name for the configuration file is +`install.conf.json`. ```json [ @@ -106,6 +162,7 @@ started. The convention for configuration file names is `install.conf.json`. }, { "link": { + "~/.dotfiles": "", "~/.tmux.conf": "tmux.conf", "~/.vimrc": "vimrc", "~/.vim": "vim/"