DotFiles with TopGit
====================
Antonio Ospite <ospite@studenti.unina.it>
v1.0, March 2011:
First version.

An experiment on managing dot-files with TopGit
(http://repo.or.cz/w/topgit.git)

Goals:

  - Manage different sets of configuration files in one repository
  - Avoid calling programs other than make and git directly as far as 
    possible
  - Have private or “local” configuration files
  - Have a .gitignore file for generated files
  - Copy configuration files to remote hosts

Non-requirements:

  - I don't need to track the files directly into '$HOME': keeping a 
    copy around is fine as long as I can easily diff with the actual 
    files in '$HOME'


The sets of configurations files will be represented with git branches, 
and a few special branches will perform a "union" operations on these 
sets producing something resembling what we want to track in the '$HOME'
dir.

TopGit has to be used by those who want to push to the remote repository
eventually, but will not be needed for those who just want to clone the
repository to reuse what is in it.

The drawback of using TopGit is that the history gets polluted with a 
lot of Merge commits, but using 'git log --no-merges' alleviate this 
problem.


Tutorial
--------

Legend

  - lines starting with '$' are shell commands
  - the symbol '*' in the branch layouts marks the currently active 
    branch
  - if the prompt looks like '[branch-name]' this is a topgit prompt 
    shown when there are conflicts to solve


Initialize the repository
~~~~~~~~~~~~~~~~~~~~~~~~~

  $ make init


Start tracking vim dot files
~~~~~~~~~~~~~~~~~~~~~~~~~~~~

  $ make add-vim

We get the branch layout below

    +------------+
    | dot-files  |
    +------------+
          |
          |
          v
   +--------------+
   | * tg/dot-vim |
   +--------------+
          |
          |
          v
    +------------+
    |   master   |
    +------------+

and we can now start tracking vim configuration files

  $ cp ~/.vimrc dot-vimrc
  $ cp -r ~/.vim dot-vim
  $ git add dot-*
  $ git commit


Start tracking bash dot files
~~~~~~~~~~~~~~~~~~~~~~~~~~~~~

  $ make add-bash

We get the layout below:

           +------------+
           | dot-files  |
           +------------+
              /     \
             /       \
            v         v
   +------------+ +---------------+
   | tg/dot-vim | | * tg/dot-bash |
   +------------+ +---------------+
            \        /
             \      /
              v    v
           +------------+
           |   master   |
           +------------+

and we ca start tracking bash confiration files

  $ cp ~/.bashrc dot-bashrc
  $ cp ~/.bash_profile dot-bash_profile
  $ cp ~/.inpurtc dot-inputrc
  $ git add dot-*
  $ git commit


Update the "union" branch
~~~~~~~~~~~~~~~~~~~~~~~~~

Update the topmost branch called 'dot-files' and install the 
configurations files

  $ make update

Check what are the differences between what is in the repository and 
what is in '$HOME':
  
  $ make diff

Finally install the version in the repsoitory replacing the on ein 
'$HOME'

  $ make install


Start a local bash branch
~~~~~~~~~~~~~~~~~~~~~~~~~
  $ make local-bash

We get the layout below:

           +-----------------+
           | dot-files-local |
           +-----------------+
              |        \
              |         \
              |          v
              |      +---------------------+
              |      | * tg/dot-bash-local |
              |      +---------------------+
              v              |
           +------------+    |
           | dot-files  |    |
           +------------+    |
              /     \        |
             /       \       |
            v         v      v
    +------------+ +-------------+
    | tg/dot-vim | | tg/dot-bash |
    +------------+ +-------------+
            \        /
             \      /
              v    v
           +------------+
           |   master   |
           +------------+

Add some personal setting

  $ echo "[ -e .bashrc-local ] && source .bashrc-local" >> dot-bashrc
  $ echo "DEBEMAIL=me@home.net" > dot-bashrc-local
  $ git add dot-bashrc-local
  $ git commit -m "Add a local bashrc"


Update all the configurations
~~~~~~~~~~~~~~~~~~~~~~~~~~~~~

This will update the 'dot-files-local' branch and all its
dependencies and install all the configurations files.

  $ make update-all
  $ make install


Push all the changes to a remote repository
~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~

  $ make push

This will *NOT* push the local stuff to the public repository



Resolving merge conflicts
-------------------------

In particular if you change Makefile or README.txt while in the master 
branch, you are likely to get conflicts when calling 'make update'.

To solve this keeping the changes from master just run these commands at 
the topgit prompt:

  [tg/dot-vim] git checkout --their Makefile README.txt
  [tg/dot-vim] git add Makefile README.txt
  [tg/dot-vim] git commit
  [tg/dot-vim] exit