Using a bare git repo to store dotfiles

What are dotfiles?

Being a Linux user allows me to configure programs and system through the use of configuration files, commonly known as dotfiles due to their usual . prefix that hides the files from file management programs. They often allow you to change many aspects of a program and setup it up exactly how you want to, from the aesthetics to the underlying behaviour.

It wasn't too long ago that my dotfiles had no organisation system in place and I had been too nervous to try to use git to manage them because of my lack of knowledge of the git program. That is until the last week or so as I have now setup my own git server using gitea through a docker container. This has allowed me to play around in a safe environment, away from public eyes and has created the ideal opportunity to get my dotfiles under control. In doing so it means whenever I setup a new system I will be able to grab all my configuration files and be setup just the way I want to without having to manually re-write all the files by hand or a basic copy and paste of each file, which would get tedious.

What is git?

git is a version control system which has taken the software world by storm in the last 20 years or so. It allows people to track changes to files creating a repository wherein a history of alterations is kept. It can be daunting to use at first, but this use case is fairly basic and is a great introduction to some git basics.

A basic git repository is created in the working directory of a project and all changes of said directory are tracked and updated as edits are made. A bare repository, however, can be an empty repository wherein you add files and directories from across a files system to the repository in order to track and store data from multiple places, ideal for a person's dotfiles!

Initialising git

In the following section it is assumed that git is already installed on the system.

In order to start storing files in a bare git repository, we first need to create one! This is easily done with the following command:

git init --bare $HOME/dotfiles

This will create a bare git repository in the directory $HOME/dotfiles, if we were to run ls on this directory we would see that git had created several directories and files within this in order to work.

From here we could start using a long to remember git command to add and track our dotfiles through this bare repository, which would look a little something like this:

git --git-dir=HOME/dotfiles --work-tree=HOME

The smarter thing to do though, is to create a command alias in our shell's configuration file to create an easy remember command to type instead of this long, difficult to remember one. By default most people's shell will be bash, we can simply edit the .bashrc file located in the user's home directory or utilise echo and redirection through standard out to achieve the same result through the command line.

echo "alias dotfiles='/path/to/git --git-dir=HOME/dotfiles --work-tree=HOME'" >>  $HOME/.bashrc

We then need to restart our shell or source the edited .bashrc dotfile.

Finally in order to clean up the output from the command about untracked files in our working tree, which in this case is our home directory (there would be a lot of untracked files) we can now use our alias to call the git program with the required options to not show untracked files:

dotfiles config --local status.showUntrackedFiles no

Now all that's left to do is to start adding files using out predefined alias, and committing them to the repository. Let's add our newly .bashrc file to repository and commit it!

dotfiles add ~/.bashrc
dotfiles commit -m "Added .bashrc, initial commit"

Tying it to a remote repository

As mentioned earlier, while having a local git repo tracking all our dotfiles is useful, it would be more useful if we had a repository hosted somewhere accessible which would allow us to pull our dotfiles down from when needed. This could be on github, gitlab, bitbucket or any other git server. In my instance I can use my own gitea server.

First create a git repo on your own git server provider and ensure it doesn't create a .gitignore or readme etc. Then on the local machine with the previously created bare dotfiles repository run the following command to add a remote origin:

dotfiles remote add origin *your.remote.url*

Then set your upstream to the origin repo you just defined.

dotfiles push --set-upstream origin master

Pull from the origin master, you may get errors saying the histories of the local and the remote repositories are unrelated, hence the allow unrelated histories flag:

dotfiles pull origin master --allow-unrelated-histories

You can now finally push the files and changes to this newly created remote repo:

dotfiles push