Dotfiles: keep your shell setup in git

Dotfiles are the hidden configuration files in your home directory: .bashrc, .zshrc, .gitconfig, .vimrc, .config/nvim, .ssh/config and so on. Years of aliases and settings live in them, and they vanish the day a laptop dies. Keeping them in a git repository gives you history, a backup and a one-command setup on every new machine or server.

Before you start

• You need git and a remote you control (GitHub, GitLab, Gitea or a bare repo on your own server).
• Decide now what is secret. ~/.ssh/id_*, ~/.aws/credentials, ~/.netrc, .env files, tokens inside .gitconfig or .npmrc and shell history must never go into the repo. If the repository is public, treat even your .ssh/config host list as sensitive.

Layout 1: a bare repository with a git alias

This layout tracks files directly in your home directory without turning ~ itself into a repository. The git directory lives in ~/.dotfiles and a shell alias points git at it.

git init --bare "$HOME/.dotfiles"
alias dot='git --git-dir="$HOME/.dotfiles" --work-tree="$HOME"'
dot config status.showUntrackedFiles no

dot add .bashrc .zshrc .gitconfig .vimrc .config/nvim
dot commit -m "Initial dotfiles"
dot remote add origin [email protected]:you/dotfiles.git
dot push -u origin main

Add the alias dot=... line to your .bashrc or .zshrc (which is itself tracked) so it exists everywhere. status.showUntrackedFiles no keeps dot status from listing every file in your home directory.

On a new machine:

git clone --bare [email protected]:you/dotfiles.git "$HOME/.dotfiles"
alias dot='git --git-dir="$HOME/.dotfiles" --work-tree="$HOME"'
dot checkout
dot config status.showUntrackedFiles no

If dot checkout complains that existing files would be overwritten (a fresh system often ships a default .bashrc), move those files aside first: mkdir -p ~/.dotfiles-backup && mv ~/.bashrc ~/.dotfiles-backup/, then run the checkout again.

Layout 2: a normal repository plus symlinks

The other common approach is an ordinary repo in ~/dotfiles with a small install script that symlinks each file into place. It is easier to understand and to browse, and GNU Stow can do the linking for you.

mkdir -p ~/dotfiles/bash ~/dotfiles/git
mv ~/.bashrc ~/dotfiles/bash/.bashrc
mv ~/.gitconfig ~/dotfiles/git/.gitconfig
cd ~/dotfiles && git init && git add . && git commit -m "Initial dotfiles"

# Link everything back with GNU Stow (brew install stow / apt install stow)
cd ~/dotfiles
stow bash git
ls -l ~/.bashrc     # -> dotfiles/bash/.bashrc

Machine-specific and secret settings

Keep the shared repo clean and let each machine add its own layer. At the end of .bashrc or .zshrc, source an untracked local file if it exists:

[[ -f "$HOME/.bashrc.local" ]] && source "$HOME/.bashrc.local"

Git supports the same idea natively. Keep ~/.gitconfig tracked and put your work email or signing key in an untracked file:

# in ~/.gitconfig (tracked)
[include]
    path = ~/.gitconfig.local

[includeIf "gitdir:~/work/"]
    path = ~/.gitconfig.work

Add a .gitignore inside the repo (or a global one at ~/.config/git/ignore) that lists the files you never want tracked, for example .ssh/id_*, .*_history, .netrc and *.local. Before the first push, run dot ls-files or git ls-files and read the list.

Check that it works

1. Open a new terminal and confirm your aliases and prompt are there.
2. Run git ls-files (or dot ls-files) and confirm no key, token or history file is listed.
3. Clone the repository into a throwaway VM or container and run the setup steps; fix anything that assumed a tool you forgot to install.

Next steps

• Add an install.sh that installs the packages your config depends on (fzf, ripgrep, stow) and then links the files.
• Use branches or includeIf for work versus personal machines instead of copying the repo.
• If you ever committed a secret, rotate it. Removing it from history is not enough once it has been pushed.

Official documentation

• git-config: Includes and includeIf
• GNU Stow manual
• GitHub does dotfiles (community guide)