X-Git-Url: https://git.madduck.net/code/vcsh.git/blobdiff_plain/88084aa515b92d5889b73b60950dee9fcbcf60a7..4327b9b3c0a74b45c670f5af44700ef8d4579d8e:/README.md?ds=sidebyside diff --git a/README.md b/README.md index 21b22d9..763b7c4 100644 --- a/README.md +++ b/README.md @@ -1,129 +1,77 @@ -vcsh - manage and sync config files via git - -# 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. - -vcsh was designed with mr [1] in mind so you might want to install that, as -well. - -Read INSTALL.md for detailed setup instructions. - -Questions? RichiH@{Freenode,OFTC,IRCnet} - -## 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 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** 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 [1], it makes it very easy to enable/disable -and clone a large number of repositories. The use of mr is technically -optional, 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 - |-- .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 - -In this setup, ~/.mrconfig looks like: - - [DEFAULT] - jobs = 5 - include = cat ~/.config/mr/config.d/* - -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. - - [$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. - -~/.config/vcsh/repo.d is the directory into which vcsh clones the git -repositories. Since their working trees are configured to be in $HOME, the -files contained in those repositories will be put in $HOME directly (see .zshrc -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` -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/ +vcsh - Version Control System for $HOME - multiple Git repositories in $HOME + + +# Index + +1. [30 Second How-to](#30-second-how-to) +2. [Introduction](#introduction) +3. [Contact](#contact) + + +# 30 Second How-to + +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. + +Let's say you want to version control your `vim` configuration: + + 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 + +If all that looks a _lot_ like standard `git`, that's no coincidence; it's +a design feature. + + +# Introduction + +[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. + +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. + +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. + +## Talks + +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]. + + +# Contact + +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. + +* IRC: #vcs-home on irc.oftc.net + +* Mailing list: [http://lists.madduck.net/listinfo/vcs-home][vcs-home-list] + +* Pull requests or issues on [https://github.com/RichiH/vcsh][vcsh] + + +[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