Home Directory in Git
Contents
The standard advice for tracking dotfiles is to symlink them from some repo into
$HOME. It works, but it means your editor shows ~/.zshrc as a symlink, your
grep has to follow links, and you’re always one ls -la away from explaining
the indirection to yourself again.
There’s a cleaner approach. Keep the git directory somewhere out of the way, and
point the work tree directly at $HOME. No symlinks.1
The Problem with $HOME/.git
The naive version, git init ~, creates ~/.git. That breaks every other git
repo under your home directory. Git walks parent directories looking for .git,
so a repo in ~/src/myproject suddenly has a second .git ancestor. Commands
behave unpredictably. Some tools refuse to run. It’s a mess.
The Detached Work Tree
Git supports separating the git directory from the work tree. Normally they’re the same place. They don’t have to be.
mkdir ~/.home
cd ~/.home
git init .
Now the git directory is ~/.home/.git and the work tree, by default, is
~/.home. The trick is to override the work tree when you run commands:
git --git-dir ~/.home/.git --work-tree=$HOME status
That’s verbose. Wrap it in an alias:
alias home='git --git-dir ~/.home/.git --work-tree=$HOME'
Add that to your shell config and home becomes your command for all dotfile
operations. home status, home add ~/.zshrc, home diff, home log—all
work exactly as you’d expect, operating on $HOME as the work tree.
Ignoring Almost Everything
The work tree is your entire home directory. Git would want to track all of it. You don’t want that.
The solution is to invert the normal ignore logic. Start by ignoring everything, then punch holes for the files you actually want to track.
In ~/.gitignore:
# Ignore everything by default
*
# Then whitelist what you want tracked
!.gitignore
!.zshrc
!.bashrc
!.profile
# ... and so on
This is the opposite of how most .gitignore files work. Normally you list
what to exclude. Here you list what to include. It feels backwards until you
internalize it, and then it feels exactly right—you’re opting in to tracking,
not opting out.
A second file, ~/.home/gitignore_global, holds generic ignore rules that
should apply to every repo (.DS_Store, swap files, and so on). Configure it
as your global excludes file:
git config --global core.excludesfile ~/.home/gitignore_global
This keeps the home-repo whitelist logic separate from the universal noise filter.
Adding a File
To start tracking a file:
home add ~/.zshrc
home commit -m "track zshrc"
To see everything currently tracked:
home ls-tree -r HEAD --name-only
To check what’s modified:
home status
home diff
Everything else works the same way. The work tree just happens to be $HOME
instead of the repo directory.
direnv Integration
One inconvenience with the detached work tree: tools that expect to find .git
in the current directory won’t find it in ~/.home. VS Code’s git integration,
for example, won’t pick up the repo automatically.
The fix is direnv. The file ~/.home/.envrc sets the relevant environment
variables:
export GIT_DIR=~/.home/.git
export GIT_WORK_TREE=~
When you cd ~/.home, direnv loads those variables. VS Code launched from that
directory picks them up before it starts. The git panel works.
The workflow for editing dotfiles in VS Code:
cd ~/.home
code ../.home.code-workspace
The cd before code is load-bearing. direnv has to set the environment
before VS Code starts, not after.
Shell Config Structure
Most home-directory setups have the same problem the dotfile repo itself has:
duplication. .bashrc and .zshrc each define the same aliases, the same
PATH additions, the same prompt logic. When you change something, you change it
twice and forget.
My approach factors shared config into files that both shells source:
~/.home/
profile # entry point: sources path and aliases, handles login-shell differences
aliases # all aliases, shared between bash and zsh
path # all PATH manipulation
prompt # shared prompt helper functions
bashrc # bash-specific interactive setup, sources prompt
zshrc # zsh-specific interactive setup, sources prompt
profile is the entry point for login shells. .bash_profile, .zprofile,
and .profile in $HOME are all symlinks to ~/.home/profile. That file
sources path and aliases, then detects the current shell:
[ -e $HOME/.home/path ] && source $HOME/.home/path
[ -e $HOME/.home/aliases ] && source $HOME/.home/aliases
if [ -n "$BASH_VERSION" ]; then
# Login bash doesn't automatically read ~/.bashrc
if [[ $- == *i* ]]; then
source "$HOME/.bashrc"
fi
elif [ -n "$ZSH_VERSION" ]; then
# Zsh already reads ~/.zshrc for interactive shells; nothing to do here
:
fi
Bash and Zsh handle the login/interactive split differently. Bash reads
.bash_profile for login shells but not .bashrc. Zsh reads .zprofile for
login shells and .zshrc for interactive shells separately. This detection
block compensates so that both shells end up with the same environment regardless
of how they started.
The shell-specific files (bashrc, zshrc) are tracked in the repo and
symlinked from $HOME. They handle the things that genuinely differ: Zsh
plugins, Bash options, completion setup. Shared behavior lives in aliases,
path, and prompt.
Setting Up from Scratch
On a new machine:
# Create the repo
mkdir ~/.home && cd ~/.home && git init .
# Add the alias immediately so you can use it
echo "alias home='git --git-dir ~/.home/.git --work-tree=\$HOME'" >> ~/.bashrc
source ~/.bashrc
# Add a remote and pull your dotfiles
home remote add origin [email protected]:you/dotfiles.git
home fetch
home checkout main
The checkout step will refuse to overwrite existing files. If you have a
.zshrc in place already, git will complain. Either back up and remove the
conflicting files first, or use home checkout main -- specific/file to pull
individual files.
On an established machine, the day-to-day is:
home status # what's changed
home add ~/.zshrc # stage a file
home commit -m "..."
home push
Same as any git repo. The alias does the heavy lifting.
The core idea comes from Ferdinand Kasper’s 2015 post: https://www.electricmonk.nl/log/2015/06/22/keep-your-home-dir-in-git-with-a-detached-working-directory/ ↩︎