VCSH is for versioning your home directory’s content using a VCS.

The manual is good, the concepts one needs to understand for using it are not very complex, and there are a lot of other articles on the web about it, so this one is very terse and focuses on how to use VCSH, not how it actually works, see the VCSH documentation and source code for details. It’s meant as a quickstart guide and reminder for how to use it.

This article does not cover how to install vcsh on your system, how to use git, how to organize your home directory, etc.


## Why VCSH?

Over time most users customize the software they use, e.g. their shell, mailclient, editor, ssh client, etc. They want to use these custom configs on other machines, have a history of their changes, a backup, the possibility to share (part of) them with other people, …

Not all software has a directory for their configs, some simply have one file directly in the home directory and do not support anything else, or don’t like having a .git subdirectory in their config directory.

This is where VCSH comes in:

* stores repositories in one location (~/.config/vcsh/repo.d/)
* manages files in the same directory (think ~/.bashrc and ~/.vimrc) in separate repositories
* provides commands for managing multiple repositories simultaneously

One of my main use cases is bootstrapping my home directory on freshly setup machines.


## Basic Usage

### Creating New and Listing VCSH Repositories

Examples:

~~~ shell
vcsh init bash
vcsh init zsh
vcsh init vim
~~~

Creates e.g. ~/.config/vcsh/repo.d/bash.git as a bare git repository.

vcsh list

will show you all your repositories.


### Managing A VCSH Repository

~~~ shell
vcsh enter bash
git add .bashrc
git commit -m "Add .bashrc"
~~~

Spawns a new shell "in the bash repository". Any git commands will operate on the bash repository. Git will behave as if your home directory was a git repository.

Leaving the shell with ctrl-d will get you back to a "normal" shell. Then you can

~~~ shell
vcsh enter vim
~~~

to "enter" the vim repo.

The point of VCSH is to make each repositories track a subset of the files in your home directory without conflicting with each other. So the "bash" repository, at this point, only tracks ~/.bashrc, while the "vim" repository does not track any files yet.


### That’s The Basics

This covers basic usage of VCSH, everything else is just git and you can do all the basic stuff like add files, add remotes, create branches, push, pull, etc., which is enough for a lot of things and most use cases mentioned above.


### Bootstrapping Your Home Directory On A New Machine