really short version

dotVC is a bash script to assist you with managing your dot-files in your home directory using multiple repositories to adapt to the need in different environments. there's also a CHANGELOG available.

slightly longer version

i recently stumbled upon the mnemonikk's blogpost Finally putting my personal configuration files under version control which remined me of my big TODO list. i chose mercurial as my SCM. for some time i was using it happily with the .hgignore hack mentioned in the comments.

but when i started using it on many systems it became odd since i had to decide whether to put a config in or not. sometimes there are systems you don't want or need a single config file to go.

this time when i looked at the setup script again and saw that it might be useful with multiple repositories.

so what you'll find here is a rewritten version of mnemonikk's setup script that supports many repositories. it uses the config file ~/.dotVC (which it can generate itself) to let you decide on each system which file in your homedir should be symlinked from which repository. additionally it can generate a file by combining the snippets from multiple repositories, concanating them. (obviously this won't work for all config files, but does at least for ssh and mercurial which i needed)


let's take a look at part of my home directory on my notebook. there i usually have all repositories available in use.

as you can see my ~/.vc/ directory contains three repositories (common, work and private). these are mercurial repositories for different tasks. they share some files, but not their contents. all the other files (~/.ssh/config, ~/.hgrc, ~/.htoprc and ~/.zshrc) are either generated from multiple repositories or symlinked to one corresponding file in a repository.

most of my config is in the common repository, since most programs use settings you can use on all machines (~/.zshrc). however my .htoprc is special, since i need another layout at work that don't fit my notebook.

as i sometimes use my private notebook at work it becomes handy to have access to all special configurations of my work machines, too. i don't have a problem having a huge ~/.ssh/config with all the machines i know on my private notebook, but the other way round wouldn't be nice. i don't want my private systems be configured on any work machine. therefore at work i'm using a different .dotVC config that just symlinks to ~/.vc/work/.ssh/config.

+- ...
+- .ssh/                   \  generated config: concatenated version of
|  +- config               /  ~/.vc/work/.ssh/config and ~/.vc/private/.ssh/config
+- .vc/                    -  version control repository base
|  +- common/              -  repository of files that can be used on all systems
|  |  +-.hgrc              -  common settings of my mercurial config (without ui.username!)
|  |  +-.zshrc             -  my zsh config
|  |
|  +- work/                -  repository with settings i use at work
|  |  +-.ssh/
|  |  | +- config          -  host definitions, ports and users of my systems at work
|  |  +-.hgrc              -  personal mercurial config (ui.username = work email address)
|  |  +-.htoprc            -  htop configured for displaying details of machines with many cores
|  |  +-.zshrc
|  |
|  +- private/             -  repository with settings i use in my spare time
|  |  +-.ssh/
|  |  | +- config          -  host definitions, ports and users of my private systems
|  |  +-.hgrc              -  personal mercurial config (ui.username = private email address)
|  |  +-.htoprc            -  htop configured for displaying on a single core machine :(
|  |
|  +- .dotVC               -  config file of dotVC
|  +- dotVC                -  the script this page is explaining
+- .hgrc                   -  generated: concatenated ~/.vc/common/.hgrc and ~/.vc/private/.hgrc
+- .htoprc                 -  symlink to: ~/.vc/private/.htoprc
+- .zshrc                  -  symlink to: ~/.vc/common/.zshrc

the corresponding ~/.vc/.dotVC config file would look like this:

# in this file you can define the mappings which file to take from which repository.
# lines starting with a hashmark (#) are ignored.
# for each file there is a mapping in the following form:
# relative/path/to/file
# repository
# which means that the file "relative/path/to/file" is symlinked from the repository "repository" 
# to the parent directory.
# if more than one repository is specified, the corresponding file is generated by concatenating 
# a combined version from all repositories in the order given.
# this file was generated to include all files from all repositories found.
# all repositories are commented out by default, so you just need to uncomment from which one to pick a file.
# place this file (.dotVC) in your .vc directory (the same as this script)






a template for this file was generated by running:

~/.vc/dotVC -t

more details can be found in the comment ahread the actual config.


~/.vc/dotVC -f

to generate the files according to your config.
repeat that step everytime you update your repositories.
remember to adapt your config file before each time you add/remove files in a repository.


i will demonstrate you how to start using it by showing what to do when you log into a new machine for the first time:

  1. create ~./vc/ directory:
  2. mkdir ~/.vc
  3. clone all the repositories you want to use on that machine inside that directory. (i use mercurial - others like git are fine, too)
    it's good to choose a "master" repository for each kind on a reachable system suitable for its environment:
  4. cd ~/.vc
    hg clone ssh://
    hg clone ssh://
    hg clone ssh://
  5. place the dotVC bash script into ~/.vc/, too.
    chmod a+rx dotVC
    i have mine checked into common repository, so i can skip this and bootstrap the process by letting it symlink itself:
  6. cd common/bin/
    ./dotVC -b
    cd -
  7. if you have already a valid .dotVC config file for the kind of machine you are preparing that is checked in, you can symlink it likewise. i took mine from the private repository, since i'm setting up a new notebook in my home:
    ln -s private/.dotVC
    if you've got exactly one repository the bootstrapping process above will symlink it for you. if you've got more, they're shown.
    or if you don't just generate a new template and edit it to fit your new environment:
  8. ./dotVC -t >.dotVC
    $EDITOR .dotVC
  9. now i encourage you to put that file under version control if you know you'll have similar machines to work on. once checked in, replace that file with a symlink to its repository copy like shown above. this way getting all my configs to a new machine is done usually in less than one minute!

on my TODO list is adding an option to rescan for new files in the repositories that are not in your config file yet and generate templates for them to be added by you. this should work similar to

~/.vc/dotVC -f