This is the documentation for my personal dotfiles repository. I wanted a lean, simple way to track and replicate my system configurations across my machines.
This uses the bare Git repository method (original author unknown). It’s mentioned in various repos1 and blog posts2, with the earliest trace I found in a 2016 Hacker News post by user StreakyCobra3.
I personally find this method to be quite elegant. There are no dependencies on external tools, no symlinks, and it’s easy to replicate the configuration on a new machine.
Example Usage
We are simply using git but with an alias of dotfiles. Add, commit, and push to update the dotfiles repo using familiar git commands.
dotfiles status
dotfiles add .vimrc
dotfiles commit -m "Add vimrc"
dotfiles add .bashrc
dotfiles commit -m "Add bashrc"
dotfiles pushPrerequisites
macOS
brew install starship kitty nvim bat ezaUbuntu/Debian
sudo apt install git starship kitty nvim bat ezaInstalling dotfiles onto a new system
# Clone dotfiles repository to the $HOME with SSH, requires SSH key
git clone --bare --recurse-submodules [email protected]:simonyjung/dotfiles.git $HOME/.dotfiles
# For a public user, use https to clone instead. Won't be able to commit/push
git clone --bare --recurse-submodules https://github.com/simonyjung/dotfiles.git $HOME/.dotfiles
# Define the alias in the current shell scope
alias dotfiles='/usr/bin/git --git-dir=$HOME/.dotfiles/ --work-tree=$HOME'
# Checkout content from the bare repository to $HOME
dotfiles checkout main
# Set local repo settings to ignore untracked files and use a custom excludesFile
dotfiles config --local status.showUntrackedFiles no
dotfiles config --local core.excludesFile=.dotfilesignoreIf you see an error about untracked working files being overwritten, back up or remove those files first.
# Backup offending files to .dotfiles-backup
mkdir -p .dotfiles-backup && \
dotfiles checkout 2>&1 | egrep "\s+\." | awk {'print $1'} | \
xargs -I{} mv {} .dotfiles-backup/{}Initial Setup
To create your own bare repository, follow these steps. If you are using zsh, substitute .bashrc with .zshrc.
# Initialize bare git repository at ~/.dotfiles
mkdir $HOME/.dotfiles
git init --bare $HOME/.dotfiles
# Set `dotfiles` alias in .bashrc
echo "alias dotfiles='/usr/bin/git --git-dir=$HOME/.dotfiles --work-tree=$HOME'" >> $HOME/.bashrc
# files we are not explicitly tracking yet
dotfiles config --local status.showUntrackedFiles no
dotfiles config --local core.excludesFile=.dotfilesignore
# Create .dotfilesignore to avoid recursion problems
echo ".dotfiles" >> .dotfilesignore
# Set repository origin
dotfiles push --set-upstream origin main
# Add files to repository, commit, then push
dotfiles add .dotfilesignore
dotfiles commit -m "Add .dotfilesignore"
dotfiles push