Home

Dotfiles

This is my attempt at implementing the bare git repository method for managing the dotfiles on my personal laptop, where your dotfiles live in $HOME and Git metadata lives in $HOME/.dotfiles.git (postfix as .git to suggest that this is a bare git repo).

Dotfiles are configuration files, I want to store them in a remote git repository in case my local machine fails and I lose them.

Benefits

• Keeps dotfiles versioned and backed up in a remote repository
• Allows easy synchronization across multiple machines
• Maintains clean separation between configuration files and Git metadata
• Enables tracking of changes to your dotfiles over time

Configuration

.dotfiles.git directory

This is a bare Git repository located at $HOME/.dotfiles.git on my and maybe your local machine. This git repository stores all the Git metadata and history for the dotfiles you wish to track. It's completely separate from your actual configuration files in $HOME and managed through a git alias, which makes it possible to use aliased Git commands such as dotfiles status, dotfiles add, and dotfiles commit from the command line outside of the repository.

• This alias should be added to your .zshrc or .bashrc file, i.e.; alias dotfiles='/usr/bin/git --git-dir=$HOME/.dotfiles.git --work-tree=$HOME' for persistence between terminal sessions.

The alias is mapping from this git repository (--git-dir=$HOME/.dotfiles.git) to $HOME (--work-tree=$HOME).

Setup

Prerequisites: git, zsh or bash

Clone existing repo to a new machine

# Clone the repo into a directory called .dotfiles.git
git clone --bare https://github.com/JRRS1982/dotfiles "$HOME/.dotfiles.git"
# Use this repo to update the files in your working directory (i.e. $HOME)
dotfiles checkout
# Set git config of this repo to ignore untracked files
dotfiles config --local status.showUntrackedFiles no

If dotfiles checkout reports existing files would be overwritten, move them out of the way and retry the checkout.

How to create your own dotfiles bare repo

# Create the repo
git init --bare "$HOME/.dotfiles.git"
# Create the alias for your terminal session (or add this to your .zshrc or .bashrc file for persistence)
alias dotfiles='/usr/bin/git --git-dir=$HOME/.dotfiles.git --work-tree=$HOME'
# Configure to ignore untracked files
dotfiles config --local status.showUntrackedFiles no
# Add a remote and push
dotfiles remote add origin https://github.com/JRRS1982/dotfiles
dotfiles push -u origin master

Day-to-day usage

Check status and diffs:

# Using the alias to check the git status
dotfiles status
# Using the alias to check the status of a specific file
dotfiles diff -- ~/.zshrc

Track a new file or update an existing one:

dotfiles add ~/.zshrc
dotfiles commit -m "Update zshrc"
dotfiles push

Pull changes if there has been any:

dotfiles pull

Thanks to

• https://web.archive.org/web/20240307132655/https://engineeringwith.kalkayan.com/series/developer-experience/storing-dotfiles-with-git-this-is-the-way/ for a detailed explanation of this method
• https://askubuntu.com/questions/1316229/is-it-bad-practice-to-git-init-in-the-home-directory-to-keep-track-of-dot-files/1316230#comment2240922_1316230 where i learnt that bare git repositories typically end in .git, hence this repository is called .dotfiles.git
• https://askubuntu.com/questions/1316229/is-it-bad-practice-to-git-init-in-the-home-directory-to-keep-track-of-dot-files/1316230#1316230 where i learnt how to setup a bare git repository
• https://news.ycombinator.com/item?id=11071754 where i read more about bare git repositories
• https://coffeeaddict.dev/how-to-manage-dotfiles-with-git-bare-repo/ this article for guarding against the git add . command by using a .gitignore file with * by default.