If you're anything like me (and don't you want to be?), you probably have more than one Linux or UNIX machine that you use on a regular basis. Perhaps you've got a laptop and a desktop. Or, maybe you've got a few servers on which you have shell accounts. Managing the configuration files for applications like mutt, Irssi and others isn't hard, but the administrative overhead just gets tedious, particularly when moving from one machine to another or setting up a new machine.

Some time ago, I started using Dropbox to manage and synchronize my configuration files. What I'd done was create several folders in Dropbox, and then when I'd set up a new machine, I'd install Dropbox, sync those folders and create symlinks from the configs in those directories to the desired configuration file in my home directory. As an example, I'd have a directory called Dropbox/conf/mutt, with my .muttrc file inside that directory. Then, I'd create a symlink like ~/.muttrc -> Dropbox/conf/mutt/.muttrc. This worked, but it quickly got out of hand and became a major pain in the neck to maintain. Not only did I have to get Dropbox working on Linux, including my command-line-only server machines, but I also had to ensure that I made a bunch of symlinks in just the right places to make everything work. The last straw was when I got a little ARM-powered Linux machine and wanted to get my configurations on it, and realized that there's no ARM binary for the Dropbox sync dæmon. There had to be another way.

...and There Was Another Way

It turns out I'm not the only one who's struggled with this. vcsh developer Richard Hartmann also had this particular itch, except he came up with a way to scratch it: vcsh. vcsh is a script that wraps both git and mr into an easy-to-use tool for configuration file management.

So, by now, I bet you're asking, "Why are you using git for this? That sounds way too complicated." I thought something similar myself, until I actually started using it and digging in. Using vcsh has several advantages, once you get your head around the workflow. The first and major advantage to using vcsh is that all you really need is git, bash and mr—all of which are readily available (or can be built relatively easily)—so there's no proprietary dæmons or services required. Another advantage of using vcsh is that it leverages git's workflow. If you're used to checking in files with git, you'll feel right at home with vcsh. Also, because git is powering the whole system, you get the benefit of having your configuration files under version control, so if you accidentally make an edit to a file that breaks something, it's very easy to roll back using standard git commands.

Let's Get Started!

I'm going to assume you're on Ubuntu 12.04 LTS or higher for this, because it makes installation easy. A simple sudo apt-get install vcsh mr git will install vcsh and its dependencies. If you're on another Linux distro, or some other UNIX derivative, you may need to check out vcsh and mr, and then build git if it's not packaged. I'm also going to assume you've got a working git server installed on another machine, because vcsh really shines for helping keep your configs synchronized between machines.

Once you've installed vcsh and its dependencies, it's time to start using vcsh. Let's take a fairly common config file that most everyone who's ever used a terminal has—the config file for vim. This file lives in your home directory, and it's called .vimrc. If you've used vim at all before, this file will be here. I'm going to show you how to get it checked into a git repository that is under vcsh's control.

First, run the following command to initialize vcsh's git repository for vim:

bill@test:~$ vcsh init vim
vcsh: info: attempting to create '/home/bill/.config/vcsh/repo.d'
vcsh: info: attempting to create '/home/bill/.gitignore.d'
Initialized empty Git repository in 
 ↪/home/bill/.config/vcsh/repo.d/vim.git/

I like to think of the "fake git repos" that vcsh works with to be almost like chroots (if you're familiar with that concept), as it makes things easier to work with. You're going to "enter a chroot", in a way, by telling vcsh you want to work inside the fake git repo for vim. This is done with this command:

bill@test:~$ vcsh enter vim

Now, you're going to add the file .vimrc to the repository you created above by running the command:

bill@test:~$ git add .vimrc

You're using normal git here, but inside the environment managed by vcsh. This is a design feature of vcsh to make it function very similarly to git.

Now that your file's being tracked by the git repository inside vcsh, let's commit it by running the following git-like command:

bill@test:~$ git commit -m 'Initial Commit'
master (root-commit) bc84953 Initial Commit
 Committer: Bill Childers bill@test.home
 1 file changed, 2 insertions(+)
 create mode 100644 .vimrc

Now for the really cool part. Just like standard git, you can push your files to a remote repository. This lets you make them available to other machines with one command. Let's do that now. First, you'll add the remote server. (I assume you already have a server set up and have the proper accounts configured. You'll also need a bare git repo on that server.) For example:

bill@test:~$ git remote add origin git@gitserver:vim.git

Next, push your files to that remote server:

bill@test:~$ git push -u origin master
    Counting objects: 3, done.
    Compressing objects: 100% (2/2), done.
    Writing objects: 100% (3/3), 272 bytes, done.
    Total 3 (delta 0), reused 0 (delta 0)
    To git@gitserver:vim.git
    * new branch      master -> master
    Branch master set up to track remote branch master from origin.
bill@test:~$ exit

Note the exit line at the end. This exits the "vcsh fake git repo". Now your .vimrc file is checked in and copied to a remote server! If there are other programs for which you'd like to check in configurations, like mutt, you simply can create a new repo by running vcsh init mutt, and then run through the process all over again, but this time, check your files into the mutt repository.

Move Your Configuration to Another Machine

To sync your configuration to another machine, you just need to install vcsh, git and mr, and then run a similar process as the steps above, except you'll do a git pull from your server, rather than a push. This is because you don't have the .vimrc file you want locally, and you want to get it from your remote git repository.

The commands to do this are:

bill@test2:~$ sudo apt-get install vcsh git mr
bill@test2:~$ vcsh enter vim
bill@test2:~$ git remote add origin git@gitserver:vim.git
bill@test2:~$ git pull -u origin master
From gitserver:vim
* branch            master     -> FETCH_HEAD
bill@test2:~$ exit

Now you've got your checked-in .vimrc file on your second host! This process works, but it's a little clunky, and it can become unwieldy when you start spawning multiple repositories. Luckily, there's a tool for this, and it's called mr.

Wrapping It All Up with mr

If you plan on using multiple repositories with vcsh (and you should—I'm tracking 13 repositories at the moment), getting a configuration set up for mr is essential. What mr brings to the table is a way to manage all the repositories you're tracking with vcsh. It allows you to enable and disable repositories simply by adjusting one symlink per repository, and it also gives you the ability to update all your repos simply by running one easy command: mr up.

Perhaps the best way to get started using mr is to clone the repo that the vcsh author provides. This is done with the following command:

bill@test2:~$ vcsh clone 
 ↪git://github.com/RichiH/vcsh_mr_template.git mr
Initialized empty Git repository in 
 ↪/home/bill/.config/vcsh/repo.d/mr.git/
remote: Counting objects: 19, done.
remote: Compressing objects: 100% (14/14), done.
remote: Total 19 (delta 1), reused 15 (delta 0)
Unpacking objects: 100% (19/19), done.
From git://github.com/RichiH/vcsh_mr_template
* new branch      master     -> origin/master

Now that you've got your mr repo cloned, you'll want to go in and edit the files to point to your setup. The control files for mr live in ~/.config/mr/available.d, so go to that directory:

bill@test2:~/.config/mr/available.d$ ls
mr.vcsh  zsh.vcsh

Rename the zsh.vcsh file to vim.vcsh, because you're working with vim, and change the repository path to point to your server:

bill@test2:~/.config/mr/available.d$ mv zsh.vcsh vim.vcsh
bill@test2:~/.config/mr/available.d$ vi vim.vcsh
[$HOME/.config/vcsh/repo.d/vim.git]
checkout = vcsh clone git@gitserver:vim.git vim

Also, edit the mr.vcsh file to point to your server as well:

bill@test2:~/.config/mr/available.d$ vi mr.vcsh
[$HOME/.config/vcsh/repo.d/mr.git]
checkout = vcsh clone git@gitserver:mr.git mr

The mr tool relies on symlinks from the available.d directory to the config.d directory (much like Ubuntu's Apache configuration, if you're familiar with that). This is how mr determines which repositories to sync. Since you've created a vim repo, make a symlink to tell mr to sync the vim repo:

bill@test2:~/.config/mr/available.d$ cd ../config.d
bill@test2:~/.config/mr/config.d$ ls -l
total 0
lrwxrwxrwx 1 bill bill 22 Jun 11 18:14 mr.vcsh -> 
 ↪../available.d/mr.vcsh
bill@test2:~/.config/mr/config.d$ ln -s 
 ↪../available.d/vim.vcsh vim.vcsh
bill@test2:~/.config/mr/config.d$ ls -l
total 0
lrwxrwxrwx 1 bill bill 22 Jun 11 18:14 mr.vcsh -> 
 ↪../available.d/mr.vcsh
lrwxrwxrwx 1 bill bill 23 Jun 11 20:51 vim.vcsh -> 
 ↪../available.d/vim.vcsh

Now, set up mr to be able to sync to your git server:

bill@test2:~/.config/mr/config.d$ cd ../..
bill@test2:~/.config$ vcsh enter mr
bill@test2:~/.config$ ls
mr  vcsh
bill@test2:~/.config$ git add mr
bill@test2:\~/.config$ git commit -m 'Initial Commit'
[master fa4eb18] Initial Commit
Committer: Bill Childers [bill@test2.home]
3 files changed, 4 insertions(+), 1 deletion(-)
create mode 100644 .config/mr/available.d/vim.vcsh
create mode 120000 .config/mr/config.d/vim.vcsh
bill@test2:\~/.config$ git remote add origin git@gitserver:mr.git
fatal: remote origin already exists.

Oh no! Why does the remote origin exist already? It's because you cloned the repo from the author's repository. Remove it, then create your own:

bill@test2:~/.config$ git remote show
origin
bill@test2:~/.config$ git remote rm origin
bill@test2:~/.config$ git remote add origin git@gitserver:mr.git
bill@test2:~/.config$ git push -u origin master
Counting objects: 28, done.
Compressing objects: 100% (21/21), done.
Writing objects: 100% (28/28), 2.16 KiB, done.
Total 28 (delta 2), reused 0 (delta 0)
To git@gitserver:mr.git
 * [new branch]      master -> master
Branch master set up to track remote branch master from origin.
bill@test2:~/.config$ exit

That's it! However, now that mr is in the mix, all you need to do to set up a new machine is do a vcsh clone git@gitserver:mr.git mr to clone your mr repository, then do an mr up, and that machine will have all your repos automatically.

Conclusion

vcsh is a very powerful shell tool, and one that takes some time to adapt your thought processes to. However, once you do it, it makes setting up a new machine (or account on a machine) a snap, and it also gives you a way to keep things in sync easily. It's saved me a lot of time in the past few months, and it's allowed me to recover quickly from a bad configuration change I've made. Check it out for yourself!

Setting up a Remote Git Repo

A quick note on setting up a remote git repo: you'll need to set up passwordless authentication using SSH keys (see Resources for more information). Once you have that going using a "git" user, you simply need to create a git repo as the git user. That's done easily enough, just run the command:

git@gitserver:~$ git init --bare vim.git
Initialized empty Git repository in /home/git/vim.git/

Your bare repo will be ready for your vcsh client to check in stuff!

Resources

vcsh Home Page: http://github.com/RichiH/vcsh

mr Home Page: http://joeyh.name/code/mr

vcsh Background Slides: https://raw.github.com/RichiH/talks/slides/2012/fosdem/vcsh/fosdem-2012-vcsh-talk.pdf

How to Set Up Your Own Git Server: http://tumblr.intranation.com/post/766290565/how-set-up-your-own-private-git-server-linux

Set Up Passwordless SSH Key-Based Authentication: http://askubuntu.com/questions/46930/how-can-i-set-up-password-less-ssh-login