at⋅a⋅rax⋅is

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.