# Index
-1. [Introduction](#introduction)
-2. [30 second howto](#30-second-howto)
-3. [Overview](#overview)
-4. [Getting Started](#getting-started)
-5. [Usage Exmaples](#usage-examples)
+1. [30 second howto](#30-second-howto)
+2. [Introduction](#introduction)
+3. [Usage Exmaples](#usage-examples)
+4. [Overview](#overview)
+5. [Getting Started](#getting-started)
6. [Contact](#contact)
+# 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
+[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` are stored in `$HOME` but you can override this setting if you want to.
+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
or available to root and you may want to maintain different configuration for
`ssh` on your personal and your work machines.
-`vcsh` was designed with [mr][mr], a tool to manage Multiple Repositories, in
-mind and the two integrate very nicely. `mr` has native support for `vcsh`
-repositories and to `vcsh`, `mr` is just another configuration to track.
-This make setting up any new machine a breeze. It takes literally less than
-five minutes to go from standard installation to fully set up system
-
A lot of modern UNIX-based systems offer pacakges 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
## Talks
Some people found it useful to look at slides and videos explaining how `vcsh`
-works instead of working through the docs, first.
-They can all be found [on the author's talk page][talks].
+works instead of working through the docs.
+All slides, videos, and further information can be found
+[on the author's talk page][talks].
-# 30 second howto
+# Usage Examples
-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.
+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. This will be covered in the advanced sections.
-Let's say you want to version control your `vim` configuration:
+## Initialize a new repository "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 'Initial commit of my Vim configuration'
- # optionally push your files to a remote
+ vcsh vim commit -m 'Update Vim configuration'
+
+## Add a remote for repository "vim"
+
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 origin master:master
+ vcsh vim branch --track master origin/master
+
+## Push to remote of repository "vim"
+
vcsh vim push
-If all that looks a _lot_ like standard `git`, that's no coincidence; it's
-a design feature.
+## Pull from remote of repository "vim"
+
+ vcsh vim pull
+
# Overview
takes care of pulling in and pushing out new data for a variety of version
control systems.
+`vcsh` was designed with [mr][mr], a tool to manage Multiple Repositories, in
+mind and the two integrate very nicely. `mr` has native support for `vcsh`
+repositories and to `vcsh`, `mr` is just another configuration to track.
+This make setting up any new machine a breeze. It takes literally less than
+five minutes to go from standard installation to fully set up system
-The last logical step is to maintain all those new repositores with an automated
-tool instead of tracking them by hand.
This is where `mr` comes in. While the use of `mr` is technically
optional, but it will be an integral part of the proposed system that follows.
~ % mr -j 5 up
-# Usage Examples
-
-All examples in this section will use the short form of `vcsh` which is the
-simplest way to interface with it. If you don't know what that means simply
-ignore this fact for now and follow the examples.
-
-## Initialize a new repository "vim"
-
- vcsh init vcsh
-
-## 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"
-
- vcsh vim pull
-
-
# mr usage ; will be factored out & rewritten
### Keeping repositories Up-to-Date
projects / code / vcsh.git / blobdiff