X-Git-Url: https://git.madduck.net/code/vcsh.git/blobdiff_plain/0726be2a782800e6a3b2234054e16e1addf8ca57..df8dca367ef16c038dfb7ffd89749f2055d57385:/README.md diff --git a/README.md b/README.md index 011b41a..c0b7cd3 100644 --- a/README.md +++ b/README.md @@ -3,20 +3,42 @@ vcsh - Version Control System for $HOME - multiple Git repositories in $HOME # 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 + 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 @@ -25,12 +47,6 @@ 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. -`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 @@ -39,29 +55,45 @@ 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, 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 + +## 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 - 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 @@ -93,9 +125,12 @@ To manage both `vcsh` and other repositories, we suggest using [mr](mr). `mr` 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. @@ -358,40 +393,6 @@ mr is used to actually retrieve configs, etc ~ % 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 - -## 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 - 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