psi-jack
/
dotbot
mirror of
1
0
Fork 0
Code Issues Releases Wiki Activity

Merge branch 'joshblum/streamline-readme'

This commit is contained in:
Anish Athalye 2015-04-26 20:15:12 -04:00
parent 3c60899895 4ed3ffc411
commit aa06a18cff
1 changed files with 90 additions and 127 deletions
Show Stats Download Patch File Download Diff File Expand all files Collapse all files

217
README.md
View File

@ -6,102 +6,107 @@ Dotbot is a tool that bootstraps your dotfiles (it's a [Dot]files
control systems do more than you think. control systems do more than you think.
Dotbot is designed to be lightweight and self-contained, with no external 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 dependencies and no installation required. Dotbot can also be a drop-in
easy to configure. 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.
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
---------------------
If you want an in-depth tutorial about organizing your dotfiles, see this [blog If you want an in-depth tutorial about organizing your dotfiles, see this [blog
post][managing-dotfiles-post]. post][managing-dotfiles-post].
A great way to organize your dotfiles is having all of them in a single Get Running in 5 Minutes
(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.
Dotbot itself is entirely self contained and requires no installation (it's ### Starting Fresh?
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 Great! Just run the following command and start adding your customizations. If
-------- you're looking for [some inpiration][inspiration], we've got you covered.
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:
```bash ```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 ### Integrate with Existing Dotfiles
the latest version, you can run:
The following will help you get set up using Dotbot in just a few steps.
```bash ```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 To get started, you just need to fill in the `install.conf.yaml` and Dotbot will
shell script that calls Dotbot with the appropriate parameters. This script take care of the rest. To help you get started we have [an
simply passes its arguments to Dotbot, so the script itself will not have to be example](#full-example) config file as well as [configuration
updated once it's placed in the proper location (the Dotbot repository can be documentation](#configuration) for the accepted parameters.
updated independently).
An bootstrap install shell script for git is given in Note: The `install` script is merely a shim that checks out the appropriate
[tools/git-submodule/install][git-install]. By default, the script assumes that version of Dotbot and calls the full Dotbot installer. By default, the script
the configuration is located in `install.conf.yaml` and Dotbot is located in assumes that the configuration is located in `install.conf.yaml` the Dotbot
`dotbot`. The script automatically makes sure that the correct version of submodule is located in `dotbot`. You can change either of these parameters by
Dotbot is checked out in the submodule. 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 ### Full Example
different VCS) is fairly straightforward.
Configuration Here's an example of a complete configuration.
-------------
Dotbot uses YAML-formatted (or JSON-formatted) configuration files to let you The conventional name for the configuration file is `install.conf.yaml`.
specify how to set up your dotfiles. Currently, Dotbot knows how to `link`
files and folders, execute `shell` commands, and `clean` directories of broken ```yaml
symbolic links. - 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 **Ideally, bootstrap configurations should be idempotent. That is, the
installer should be able to be run multiple times without causing any 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 problems.** This makes a lot of things easier to do (in particular, syncing
updates between machines becomes really easy). 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. 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 Tasks are run in the order in which they are specified. Commands within a task
do not have a defined ordering. do not have a defined ordering.
@ -124,9 +129,9 @@ a trailing "/" character.
Link commands support an (optional) extended configuration. In this type of Link commands support an (optional) extended configuration. In this type of
configuration, instead of specifying source locations directly, targets are configuration, instead of specifying source locations directly, targets are
mapped to extended configuration dictionaries. These dictionaries map "path" to mapped to extended configuration dictionaries. These dictionaries map `path` to
the source path, specify "create" as true if the parent directory should be 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 created if necessary, and specify `force` as `true` if the file or directory
should be forcibly linked. should be forcibly linked.
#### Example #### Example
@ -151,13 +156,16 @@ base directory (that is specified when running the installer).
#### Format #### Format
Shell commands can be specified in several different ways. The simplest way is 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 just to specify a command as a string containing the command to be run.
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 Another way is to specify a two element array where the first element is the
commands support an extended syntax as well, which provides more fine-grained shell command and the second is an optional human-readable description.
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 Shell commands support an extended syntax as well, which provides more
this syntax, all keys are optional except for the command itself. 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 #### Example
@ -190,50 +198,6 @@ Clean commands are specified as an array of directories to be cleaned.
- clean: ['~'] - 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 Contributing
------------ ------------
@ -246,8 +210,7 @@ License
Copyright (c) 2014-2015 Anish Athalye. Released under the MIT License. See Copyright (c) 2014-2015 Anish Athalye. Released under the MIT License. See
[LICENSE.md][license] for details. [LICENSE.md][license] for details.
[template]: https://github.com/anishathalye/dotfiles_template [inspiration]: https://github.com/anishathalye/dotfiles_template#inspiration
[git-install]: tools/git-submodule/install
[managing-dotfiles-post]: http://www.anishathalye.com/2014/08/03/managing-your-dotfiles/ [managing-dotfiles-post]: http://www.anishathalye.com/2014/08/03/managing-your-dotfiles/
[contributing]: CONTRIBUTING.md [contributing]: CONTRIBUTING.md
[license]: LICENSE.md [license]: LICENSE.md