From 4ed3ffc411f662f66082dad91d4ae4ff83c04f7b Mon Sep 17 00:00:00 2001 From: Joshua Blum Date: Mon, 27 Apr 2015 02:52:24 +0300 Subject: [PATCH] Reorganize README --- README.md | 217 ++++++++++++++++++++++-------------------------------- 1 file changed, 90 insertions(+), 127 deletions(-) diff --git a/README.md b/README.md index f3a070d..86f7686 100644 --- a/README.md +++ b/README.md @@ -6,102 +6,107 @@ Dotbot is a tool that bootstraps your dotfiles (it's a [Dot]files 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 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. - -Dotbot can be a drop-in replacement for any other tool you were using to manage -your dotfiles. - -Dotfiles Organization ---------------------- +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]. -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 -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. +Get Running in 5 Minutes +--------------------------- -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`. +### Starting Fresh? -Template --------- - -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 ------ - -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 the following command from -within your git repository: +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 submodule add https://github.com/anishathalye/dotbot + git clone git@github.com:anishathalye/dotfiles_template dotfiles ``` -This locks Dotbot on the current version. At any point, to upgrade Dotbot to -the latest version, you can run: +### Integrate with Existing Dotfiles + +The following will help you get set up using Dotbot in just a few steps. ```bash -git submodule update --remote dotbot # or other path to Dotbot submodule + # 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 have a one-click (one-command) install, you can place a bootstrap install -shell script that calls Dotbot with the appropriate parameters. This script -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). +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. -An bootstrap install shell script for git is given in -[tools/git-submodule/install][git-install]. By default, the script assumes that -the configuration is located in `install.conf.yaml` and Dotbot is located in -`dotbot`. The script automatically makes sure that the correct version of -Dotbot is checked out in the submodule. +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. -This script should be **copied** into your dotfiles repository. Once the -install script has been copied into your dotfiles, there is no need to modify -the script again -- it is merely a shim that checks out the appropriate version -of Dotbot and calls the full Dotbot installer. Note that using a symbolic link -to the sample install script included in the Dotbot repository won't work -correctly -- it can actually lead to several problems. For example, when -cloning your dotfiles onto a new system, the Dotbot submodule won't be -initialized (unless you use the `--recursive` flag), so the symbolic link will -be broken, pointing to a nonexistent file. -Adapting the bootstrap script for different situations (such as using a -different VCS) is fairly straightforward. +### Full Example -Configuration -------------- +Here's an example of a complete configuration. -Dotbot uses YAML-formatted (or JSON-formatted) configuration files to let you -specify how to set up your dotfiles. Currently, Dotbot knows how to `link` -files and folders, execute `shell` commands, and `clean` directories of broken -symbolic links. +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 YAML (or JSON) arrays of tasks, where each task +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. @@ -124,9 +129,9 @@ 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 +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 @@ -151,13 +156,16 @@ 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. +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 @@ -190,50 +198,6 @@ Clean commands are specified as an array of directories to be cleaned. - 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.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"] - ] - } -] -``` - Contributing ------------ @@ -246,8 +210,7 @@ License Copyright (c) 2014-2015 Anish Athalye. Released under the MIT License. See [LICENSE.md][license] for details. -[template]: https://github.com/anishathalye/dotfiles_template -[git-install]: tools/git-submodule/install +[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