+# 30 second howto
+
+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 <remote>
+ 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` for install instructions or `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].
+
+
+# Usage Examples
+
+There are three different ways to interact with `vcsh` repositories; this
+section will only show the simplest and easiest way.
+Certain more advanced use cases require the other two ways, but don't worry
+about this for now. If you never even bother playing with the other two
+modes you will still be fine.
+`vcsh enter` and `vcsh run` will be covered in later sections.
+
+
+## Initialize a new repository called "vim"
+
+ vcsh init vim
+
+## Clone an existing repository
+
+ vcsh clone <remote> <repository_name>
+
+## Add files to repository "vim"
+
+ vcsh vim add ~/.vimrc ~/.vim
+ vcsh vim commit -m 'Update Vim configuration'
+
+## Add a remote for repository "vim"
+
+ vcsh vim remote add origin <remote>
+ vcsh vim push origin master:master
+ vcsh vim branch --track master origin/master
+
+## Push to remote of repository "vim"
+
+ vcsh vim push
+
+## Pull from remote of repository "vim"
projects / code / vcsh.git / blobdiff