An elegant way of managing your dot files with git

29 July 2022 - Linux  Config  Bash  Zsh  Terminal  Git 

How to juggle all your configuration files between machines? a question probably asked many times. Lots of people store there configuration files or also so called dotfiles in git repos to more easily share them between machine. A commonly used method is having a repo with all the dotfiles in the $HOME directory and symbolic link the config files to the desired location like so ln -s ~/.dotfiles/.zshrc ~/.zshrc. Syncing dotfiles with symbolic links can still be quite a chore especially when you clone your repo to a new machine and have to create all those symbolic links again.

Not to worry fortunately there is a more elegant way no more symbolic links and it only dependency is git.

How does it work, by making use of a bare repository you effectively only get the repository state without its working tree. With some flags you can use this repository with the $HOME directory as its working tree eliminating the need for carefully managing you symbolic links because all files are already in the right place. Neat right?

Lest get started

If you have not tracked you dotfiles in a git repo you can get started in the next section right away..

If you already have a repository skip to the "Migrate existing repository".

Setup from scratch

If you already track your dotfiles in a git repository.

with setting up your own dotfiles repo.

First things first lets create a folder for the bare repo mkdir ~/.dots next we cd ~/.dots and run git init --bare to setup our bare repo.

Next we're going to add an alias to our ~/.zshrc or ~/.bashrc add alias dots='/usr/bin/git --git-dir=$HOME/.dots/ --work-tree=$HOME' to a place of you liking, save and run source ~/.zshrc or source ~/.bashrc. Now you can use the dots alias just as how you normally use the git command in a project folder.

Lets check our repos status with dots status. As you can see git tries to make you aware that all you files in the home directory are untracked. this makes things a bit unclear. We can solve this by configuring the repo to only show changes that are already tracked by running dots config --local status.showUntrackedFiles no. If we now run dots status again we see there are no changes in the working tree.

We are all set to start tracking files. Lets commit our ~/.zshrc.

    
    dots status
dots add ~/.zshrc
dots commit -m "feat: add zsh config"

    
  

The only thing left to do is to add a remote and push our changes.

    
    dots remote add origin <your-remote-repository>
dots push

    
  

Migrate existing repository

If you are setting up from scratch you can skip this section.

If you already track your files in a git repository you can easily migrate to this approach.

First off make sure the file and folder structure of your current dotfile repository mirrors your $HOME folder one to one.

For example something like this.

    
    dotfiles
│   README.md
│   .zshrc    
│   .gitconfig
│
└───alacritty
│   │   alacritty.conf
│   
└───htop
    │   htoprc

    
  

Should be changed to resemble your home directory like so.

    
    dotfiles
│   README.md
│   .zshrc    
│   .gitconfig
│
└───.config
    │
    └───alacritty
    │   │   alacritty.conf
    │
    └───htop
        │   htoprc

    
  

Next add this alias to you shell configuration file.

    
      ~/.zshrc
    
    # ~/.zshrc

...

alias dots='/usr/bin/git --git-dir=$HOME/.dots/ --work-tree=$HOME'

...

    
  

From then on it's the same as setting up a fresh machine follow the instructions from the next section to complete your migration.

Setup a new machine

To install your dotfiles to a new machine looks something like this.

    
    git clone --bare <your-remote-repository> ~/.dots
alias dots='/usr/bin/git --git-dir=$HOME/.dots/ --work-tree=$HOME'
dots config --local status.showUntrackedFiles no 
dots checkout

    
  

Running dots checkout can result in something like this.

    
    error: The following untracked working tree files would be overwritten by checkout:
    .zshrc
Please move or remove them before you can switch branches.
Aborting

    
  

You have two options:

  1. overwrite the existing files if you feel confident you are not losing anything by running dots checkout -f.
  2. backup the existing files by renaming them like so mv ~/.zshrc ~/.zshrc.backup and when you're done, to backup your files run dots checkout again.

At this point all your dotfiles should be in the right place.

Alternatives

I prefer this method of managing dotfiles for its simplicity, but this is just one approach of many. If you're interested in other ways of managing your dotfiles I recommend checking out dotfiles.github.io. It has a lot of references of other people's dotsfiles, tutorials and projects centered around dotfiles.

Wrapping up

Hope this post helps out a fellow developer on their config journey. If you have any questions or feedback you're always welcome to send me a message on @liamederzeel.

Sources