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 <remote>
+ 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