Reorganize README
This commit is contained in:
Joshua Blum
parent
bdc1b2205f
commit
4ed3ffc411
1 changed files with 90 additions and 127 deletions
219
README.md
219
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 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
|
||||
```
|
||||
|
||||
This locks Dotbot on the current version. At any point, to upgrade Dotbot to
|
||||
the latest version, you can run:
|
||||
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.
|
||||
|
||||
```bash
|
||||
git submodule update --remote dotbot # or other path to Dotbot 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.
|
||||
|
||||
|
||||
### 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]
|
||||
```
|
||||
|
||||
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).
|
||||
The configuration file can also be written in JSON. Here is the JSON equivalent
|
||||
of the YAML configuration given above.
|
||||
|
||||
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.
|
||||
The conventional name for this file is `install.conf.json`.
|
||||
|
||||
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.
|
||||
```json
|
||||
[
|
||||
{
|
||||
"clean": ["~"]
|
||||
},
|
||||
{
|
||||
"link": {
|
||||
"~/.dotfiles": "",
|
||||
"~/.tmux.conf": "tmux.conf",
|
||||
"~/.vim": "vim/",
|
||||
"~/.vimrc": "vimrc"
|
||||
}
|
||||
},
|
||||
{
|
||||
"shell": [
|
||||
["git submodule update --init --recursive", "Installing submodules"]
|
||||
]
|
||||
}
|
||||
]
|
||||
```
|
||||
|
||||
Adapting the bootstrap script for different situations (such as using a
|
||||
different VCS) is fairly straightforward.
|
||||
## Configuration
|
||||
|
||||
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.
|
||||
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
|
||||
|
|
|
|||
Loading…
Reference in a new issue