VCSH Quickstart

• Why VCSH?
• Basic Usage
  • Creating New and Listing VCSH Repositories
  • Managing A VCSH Repository
  • That’s The Basics
• Beyond Basic
  • Backing up, publishing, sharing configs with Git
  • Bootstrapping Your Home Directory On A New Machine

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, especially some details about the integration with myrepos.

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:

1
2
3
vcsh init bash
vcsh init zsh
vcsh init vim

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

1
vcsh list

will show you all your repositories.

Managing A VCSH Repository

1
2
3
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

1
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.

Beyond Basic

Backing up, publishing, sharing configs with Git

After vcsh entering a repo you can treat it like any other git repository, in particular you can set a remote for it to push to and pull from. You don’t actually have to “enter” the repo, vcsh wraps many git commands, e.g.:

1
2
vcsh repo_name commit
vcsh repo_name push

To make this a bit easier, I deployed two of the sample_hooks coming with vcsh. On vcsh init they set a git remote and drop a config snippet in the myrepos config directory to register the repo.

Bootstrapping Your Home Directory On A New Machine

On a newly setup user account (e.g. on a freshly installed host) the bootstrap process for my user’s home directory looks something like this:

1
2
3
4
5
6
7
8
9
10
11
git config --global init.defaultBranch main
vcsh clone ssh://gitolite@git.netwichtig.de/user/henk/vcsh/mr.git
vcsh clone ssh://gitolite@git.netwichtig.ch/user/henk/vcsh/git.git
vcsh clone ssh://gitolite@git.netwichtig.ch/user/henk/vcsh/ssh.git
vcsh clone ssh://gitolite@git.netwichtig.ch/user/henk/vcsh/zsh.git
zsh
mkdir ~/.config/mr/enabled.d
cd !$
ln -s ../available.d/{aptitude.vcsh,gitignore.repo,git.vcsh,mr.vcsh,neovim.vcsh,selenized.repo,ssh.vcsh,tmux-tpm.repo,tmux.vcsh,vim-plug.repo,zgenom.repo,zsh.vcsh} .
cd
mr update

To explain:

• configure git to use ‘main’ as the default branch name, so vcsh will clone/pull from the correct branch
• use vcsh to clone the myrepos repo containing info about all other repos
• use vcsh to clone relevant other repos, so further cloning uses my optimizations and is faster and more reliable
• start a new zsh with the config we just pulled
• create the directory where mr actually reads config files from and cd to it
• symlink those repos I actually need on this machine
• cd back into my home
• make mr update all enabled repos
• relogin to use new settings

There are some other steps that are specific to some of the software I use, but that should cover everything relevant for the bootstrapping.

This sequence of commands is not quite easy to remember but it is a whole lot easier than doing it all by hand. And I wrote it down here so I can copy and paste in the future.

With this concept laid out and being able to copy&paste it, setting up my preferred working environment on a new machine is basically reduced to two handful of commands and maybe a minute of waiting for the downloads to finish.