psi-jack/dotbot
1
0
Fork 0
mirror of synced 2024-11-22 08:15:34 -05:00
Code Issues Releases Wiki Activity

Update README

Browse source 
Improve documentation with specification and an example for each type of
task.
This commit is contained in:
Anish Athalye 2014-10-22 11:10:49 -04:00
parent 1733b54c87
commit 58e4fb50b1
1 changed files with 94 additions and 37 deletions
Show stats Download patch file Download diff file Expand all files Collapse all files

131
README.md
View file

@ -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/"