-# Overview
-
-## Comparison to Other Solutions ##
-
-Most people who decide to put their dotfiles under version control start with a
-single repository in `$HOME`, adding all their dotfiles (and possibly more)
-to it. This works, of course, but can become a nuisance as soon as you try to
-manage more than one host.
-
-The next logical step is to create single-purpose repositories in, for example,
-`~/.dotfiles` and to create symbolic links into `$HOME`. This gives you the
-flexibility to check out only certain repositories on different hosts. The
-downsides of this approach are the necessary manual steps of cloning and
-symlinking the individual repositories.
-
-`vcsh` takes this second approach one step further. It expects
-single-purpose repositories and stores them in a hidden directory (similar
-to `~/.dotfiles`). However, it does not create symbolic links in `$HOME`; it
-puts the actual files right into `$HOME`.
-
-Furthermore, by making use of [mr][mr], it makes it very easy to enable/disable
-and clone a large number of repositories. The use of `mr` is technically
-optional (see section 4.3), but it will be an integral part of the proposed
-system that follows.
-
-## Default Directory Layout ##
-
-To illustrate, this is what a possible directory structure looks like.
-
- $HOME
- |-- $XDG_CONFIG_HOME (defaults to $HOME/.config)
- | |-- mr
- | | |-- available.d
- | | | |-- zsh.vcsh
- | | | |-- gitconfigs.vcsh
- | | | |-- lftp.vcsh
- | | | |-- offlineimap.vcsh
- | | | |-- s3cmd.vcsh
- | | | |-- tmux.vcsh
- | | | |-- vim.vcsh
- | | | |-- vimperator.vcsh
- | | | `-- snippets.git
- | | `-- config.d
- | | |-- zsh.vcsh -> ../available.d/zsh.vcsh
- | | |-- gitconfigs.vcsh -> ../available.d/gitconfigs.vcsh
- | | |-- tmux.vcsh -> ../available.d/tmux.vcsh
- | | `-- vim.vcsh -> ../available.d/vim.vcsh
- | `-- vcsh
- | |-- config
- | `-- repo.d
- | |-- zsh.git -----------+
- | |-- gitconfigs.git |
- | |-- tmux.git |
- | `-- vim.git |
- |-- [...] |
- |-- .zshrc <----------------------+
- |-- .gitignore.d
- | `-- zsh
- |-- .mrconfig
- `-- .mrtrust
-
-### available.d ###
-
-The files you see in $XDG\_CONFIG\_HOME/mr/available.d are mr configuration files
-that contain the commands to manage (checkout, update etc.) a single
-repository. vcsh repo configs end in .vcsh, git configs end in .git, etc. This
-is optional and your preference. For example, this is what a zsh.vcsh
-with read-only access to my zshrc repo looks likes. I.e. in this specific
-example, push can not work as you will be using the author's repository. This
-is for demonstration, only. Of course, you are more than welcome to clone from
-this repository and fork your own.
-
- [$XDG_CONFIG_HOME/vcsh/repo.d/zsh.git]
- checkout = vcsh clone 'git://github.com/RichiH/zshrc.git' zsh
- update = vcsh run zsh git pull
- push = vcsh run zsh git push
- status = vcsh run zsh git status
- gc = vcsh run zsh git gc
-
-### config.d ###
-
-$XDG\_CONFIG\_HOME/mr/available.d contains *all available* repositories. Only
-files/links present in mr/config.d, however, will be used by mr. That means
-that in this example, only the zsh, gitconfigs, tmux and vim repositories will
-be checked out. A simple `mr update` run in $HOME will clone or update those
-four repositories listed in config.d.
-
-### ~/.mrconfig ###
-
-Finally, ~/.mrconfig will tie together all those single files which will allow
-you to conveniently run `mr up` etc. to manage all repositories. It looks like
-this:
-
- [DEFAULT]
- jobs = 5
- # Use if your mr does not have vcsh support in mainline, yet
- include = cat /usr/share/mr/vcsh
- include = cat ${XDG_CONFIG_HOME:-$HOME/.config}/mr/config.d/*
-
-### repo.d ###
-
-$XDG\_CONFIG\_HOME/vcsh/repo.d is the directory where all git repositories which
-are under vcsh's control are located. Since their working trees are configured
-to be in $HOME, the files contained in those repositories will be put in $HOME
-directly.
-Of course, [mr] [1] will work with this layout if configured according to this
-document (see above).
-
-vcsh will check if any file it would want to create exists. If it exists, vcsh
-will throw a warning and exit. Move away your old config and try again.
-Optionally, merge your local and your global configs afterwards and push with
-`vcsh run foo git push`.
-
-## Moving into a New Host ##
-
-To illustrate further, the following steps could move your desired
-configuration to a new host.
-
-1. Clone the mr repository (containing available.d, config.d etc.); for
- example: `vcsh clone git://github.com/RichiH/vcsh_mr_template.git mr`
-2. Choose your repositories by linking them in config.d (or go with the default
- you may have already configured by adding symlinks to git).
-3. Make sure the line 'include = cat /usr/share/mr/vcsh' in .mrconfig points
- to an existing file
-4. Run mr to clone the repositories: `cd; mr update`.
-5. Done.
-
-Hopefully the above could help explain how this approach saves time by
-
-1. making it easy to manage, clone and update a large number of repositories
- (thanks to mr) and
-2. making it unnecessary to create symbolic links in $HOME (thanks to vcsh).
-
-If you want to give vcsh a try, follow the instructions below.
-
-
-# Getting Started #
-
-Below, you will find a few different methods for setting up vcsh:
-
-1. The Template Way
-2. The Steal-from-Template Way
-3. The Manual Way
-
-### The Template Way ###
-
-#### Prerequisites ####
-
-Make sure none of the following files and directories exist for your test
-(user). If they do, move them away for now:
-
-* ~/.gitignore.d
-* ~/.mrconfig
-* $XDG\_CONFIG\_HOME/mr/available.d/mr.vcsh
-* $XDG\_CONFIG\_HOME/mr/available.d/zsh.vcsh
-* $XDG\_CONFIG\_HOME/mr/config.d/mr.vcsh
-* $XDG\_CONFIG\_HOME/vcsh/repo.d/mr.git/
-
-All of the files are part of the template repository, the directory is where
-the template will be stored.
-
- apt-get install mr
-
-#### Install vcsh ####
-
-#### Debian ####
-
-If you are using Debian Squeeze, you will need to enable backports
-
- apt-get install vcsh
-
-#### Arch Linux ####
projects / code / vcsh.git / blobdiff