X-Git-Url: https://git.madduck.net/code/vcsh.git/blobdiff_plain/0af8c82fed06f635e0a8dfa25b26c97a7932af51..6480c1913a9853176fe527079680242dbf4d40a4:/README.md?ds=sidebyside diff --git a/README.md b/README.md index 4263ad0..763b7c4 100644 --- a/README.md +++ b/README.md @@ -1,106 +1,77 @@ -vcsh - manage and sync config files via git +vcsh - Version Control System for $HOME - multiple Git repositories in $HOME -# Introduction # -vcsh allows you to have several git repositories, all maintaining their working trees in $HOME without clobbering each other. -That, in turn, means you can have one repository per config set (zsh, vim, ssh, etc), picking and choosing which configs you want to use on which machine. +# Index -vcsh was designed with mr [1] in mind so you might want to install that, as well. +1. [30 Second How-to](#30-second-how-to) +2. [Introduction](#introduction) +3. [Contact](#contact) -Read INSTALL.md for detailed setup instructions. -Questions? RichiH@{Freenode,OFTC,IRCnet} +# 30 Second How-to -## Comparison to Other Solutions ## +While it may appear that there's an overwhelming amount of documentation and +while the explanation of the concepts behind `vcsh` needs to touch a few gory +details of `git` internals, getting started with `vcsh` is extremely simple. -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. +Let's say you want to version control your `vim` configuration: -The next logical step is to create single-purpose repositories in, for example, ~/.dotfiles and to create **symbolic links in $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. -It will probably become a nuisance when you try to manage more than two hosts. + vcsh init vim + vcsh vim add ~/.vimrc ~/.vim + vcsh vim commit -m 'Initial commit of my Vim configuration' + # optionally push your files to a remote + vcsh vim remote add origin + vcsh vim push -u origin master + # from now on you can push additional commits like this + vcsh vim push -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. +If all that looks a _lot_ like standard `git`, that's no coincidence; it's +a design feature. -Furthermore, by making use of mr [1], it makes it very easy to enable/disable and clone a large number of repositories. -## Default Directory Layout ## +# Introduction -To illustrate, this is what a possible directory structure looks like. +[vcsh][vcsh] allows you to maintain several Git repositories in one single +directory. They all maintain their working trees without clobbering each other +or interfering otherwise. By default, all Git repositories maintained via +`vcsh` store the actual files in `$HOME` but you can override this setting if +you want 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.mrconfig -> ../available.d/zsh.mrconfig - | | | |-- gitconfigs.mrconfig -> ../available.d/gitconfigs.mrconfig - | | | |-- tmux.mrconfig -> ../available.d/tmux.mrconfig - | | | `-- vim.mrconfig -> ../available.d/vim.mrconfig - | `-- vcsh - | `-- repo.d - | |-- zsh.git -----------+ - | |-- gitconfigs.git | - | |-- tmux.git | - | `-- vim.git | - |-- [...] | - |-- .zshrc <----------------------+ - |-- .gitignore - |-- .mrconfig - `-- .mrtrust +All this means that you can have one repository per application or application +family, i.e. `zsh`, `vim`, `ssh`, etc. This, in turn, allows you to clone +custom sets of configurations onto different machines or even for different +users; picking and mixing which configurations you want to use where. +For example, you may not need to have your `mplayer` configuration on a server +or available to root and you may want to maintain different configuration for +`ssh` on your personal and your work machines. -In this setup, ~/.mrconfig looks like: +A lot of modern UNIX-based systems offer packages for `vcsh`. In case yours +does not, read [INSTALL.md](doc/INSTALL.md) for install instructions or +[PACKAGING.md](doc/PACKAGING.md) to create a package yourself. If you do end +up packaging `vcsh` please let us know so we can give you your own packaging +branch in the upstream repository. - [DEFAULT] - jobs = 5 - include = cat ~/.config/mr/config.d/* +## Talks -The files you see in ~/.config/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.mrconfig with read-only access to my zshrc repo looks likes. I.e. in this specific example, push can not work. +Some people found it useful to look at slides and videos explaining how `vcsh` +works instead of working through the docs. +All slides, videos, and further information can be found +[on the author's talk page][talks]. - [$HOME/.config/vcsh/repo.d/zsh.git] - checkout = vcsh clone 'git://github.com/RichiH/zshrc.git' - update = vcsh run bash git pull - push = vcsh run bash git push - status = vcsh run bash git status -~/.config/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. +# Contact -~/.config/vcsh/repo.d is the directory where vcsh clones the git repositories into. -Since their working trees are configured to be in $HOME, the files contained in those repositories will be put in $HOME directly (see .bashrc above). +There are several ways to get in touch with the author and a small but committed +community around the general idea of version controlling your (digital) life. -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`. +* IRC: #vcs-home on irc.oftc.net -## Moving into a New Host ## +* Mailing list: [http://lists.madduck.net/listinfo/vcs-home][vcs-home-list] -To illustrate further, the following steps could move your desired configuration to a new host. +* Pull requests or issues on [https://github.com/RichiH/vcsh][vcsh] -1. Clone the mr repository (containing available.d, config.d etc.), for example: `vcsh clone git://github.com/RichiH/vcsh_mr_template.git` -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. Run mr to clone the repositories: `cd; mr update`. -4. 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). - ----------- - -[1] http://kitenet.net/~joey/code/mr/ +[myrepos]: http://myrepos.branchable.com/ +[talks]: http://richardhartmann.de/talks/ +[vcsh]: https://github.com/RichiH/vcsh +[vcs-home-list]: http://lists.madduck.net/listinfo/vcs-home