dotfiles

Use git to manage dotfiles without symlinks. This setup uses a dedicated git dir at ~/git/dotfiles with work-tree ~ (via the dotfiles wrapper). Uses nix-darwin (macOS) or home-manager (Linux) and brew (macOS) to set up and install software, and mise to manage runtimes.

Why this setup

No symlinks: tracked files live directly in $HOME.
Git metadata stays out of the way in ~/git/dotfiles.
Bootstrap is safer on existing machines where dotfiles may already exist.
Day-to-day Git UX stays reliable, including ahead-behind and push state in LazyGit.

Under the hood, git metadata is stored at ~/git/dotfiles, and core.worktree points at $HOME.

Usage

If you've already got your dotfiles setup you can use the following commands to manage your dotfiles.

Updating dotfiles

Track file

First un-ignore the file/path in ~/.gitignore, then add it:

dotfiles add .somefile

Untrack file

dotfiles rm --cached .somefile

Code quality hooks (hk)

Dotfiles use hk for fast staged-file checks on commit.

dotfiles config core.hooksPath .hk-hooks
mise install
dhk check

dotfiles commit then runs .hk-hooks/pre-commit, which calls hk run pre-commit.

Managing system

macOS (nix-darwin)

Build and activate nix-darwin config. This will make changes to the system and update packages as per flake.nix

darwin-rebuild switch --flake ~/.config/nix
# alias: drs

Update nix packages. This will update your non-homebrew packages and update flake.lock

nix flake update --flake ~/.config/nix
# alias: nfu
# You need to run build and activate after i.e. drs

Update brew packages

brew upgrade

Update mise packages

mise upgrade

Linux (home-manager)

Build and activate home-manager config. This will update packages as per flake.nix

home-manager switch --flake ~/.config/nix
# alias: hms

Update nix packages. This will update your packages and update flake.lock

nix flake update --flake ~/.config/nix
# alias: nfu
# You need to run home-manager switch after i.e. hms

Update mise packages

mise upgrade

Setup

Quick start (recommended)

If you are setting up this exact repo on Linux/Codespaces, use the bootstrap script:

curl -fsSL https://raw.githubusercontent.com/connorads/dotfiles/master/install.sh | bash

It installs dotfiles and sets upstream tracking so git status/LazyGit show ahead-behind correctly.

Manual setup (from this repo)

If you want to follow the manual path (or fork this repo), use this.

Clone using a separate git dir

DOTFILES_REPO=https://github.com/connorads/dotfiles.git
DOTFILES_DIR=$HOME/git/dotfiles
BOOTSTRAP_WORKTREE=$(mktemp -d "$HOME/.dotfiles-bootstrap.XXXXXX")

git clone --separate-git-dir="$DOTFILES_DIR" "$DOTFILES_REPO" "$BOOTSTRAP_WORKTREE"
rm -rf "$BOOTSTRAP_WORKTREE"

Why the temporary BOOTSTRAP_WORKTREE dir? git clone needs a checkout target path, and $HOME is non-empty. The temp dir keeps bootstrap safe and disposable.

Point the repo at $HOME and ensure tracking refs

git --git-dir="$DOTFILES_DIR" config core.bare false
git --git-dir="$DOTFILES_DIR" config core.worktree "$HOME"
git --git-dir="$DOTFILES_DIR" config --replace-all remote.origin.fetch "+refs/heads/*:refs/remotes/origin/*"
git --git-dir="$DOTFILES_DIR" fetch origin --prune

Check out dotfiles into $HOME (⚠️ this overwrites conflicting files)

git --git-dir="$DOTFILES_DIR" checkout 2>&1 | sed -n 's/^[[:space:]]\+//p' | while IFS= read -r file; do
  if [ -f "$file" ]; then
    mv "$file" "$file.bak"
  fi
done

git --git-dir="$DOTFILES_DIR" --work-tree="$HOME" checkout -f

Set upstream for the current branch

CURRENT_BRANCH=$(git --git-dir="$DOTFILES_DIR" symbolic-ref --quiet --short HEAD)
git --git-dir="$DOTFILES_DIR" --work-tree="$HOME" branch --set-upstream-to="origin/$CURRENT_BRANCH" "$CURRENT_BRANCH"

Set up nix, brew and install software (⚠️ skip the option to install Determinate Nix)

macOS (nix-darwin):

# Install Homebrew
/bin/bash -c "$(curl -fsSL https://raw.githubusercontent.com/Homebrew/install/HEAD/install.sh)"
eval "$(/opt/homebrew/bin/brew shellenv)"

# Install Nix
curl --proto '=https' --tlsv1.2 -sSf -L https://install.determinate.systems/nix | sh -s -- install
. /nix/var/nix/profiles/default/etc/profile.d/nix-daemon.sh

# Build and activate nix-darwin configuration
nix run nix-darwin/master#darwin-rebuild -- switch --flake ~/.config/nix

Linux (home-manager):

# Install Nix
curl --proto '=https' --tlsv1.2 -sSf -L https://install.determinate.systems/nix | sh -s -- install
. ~/.nix-profile/etc/profile.d/nix.sh

# Build and activate home-manager configuration
nix run home-manager/master -- switch --flake ~/.config/nix

Reload your shell
```
exec zsh
```

Migration helper (if needed)

If an existing machine has an older setup, run:

DOTFILES_DIR=$HOME/git/dotfiles
if [ "$(git --git-dir=$DOTFILES_DIR rev-parse --is-bare-repository 2>/dev/null || true)" = "true" ]; then
  git --git-dir=$DOTFILES_DIR config --unset core.bare || true
fi
git --git-dir=$DOTFILES_DIR config core.worktree $HOME
CURRENT_BRANCH=$(git --git-dir=$DOTFILES_DIR/ symbolic-ref --quiet --short HEAD)
git --git-dir=$DOTFILES_DIR/ config --replace-all remote.origin.fetch "+refs/heads/*:refs/remotes/origin/*"
git --git-dir=$DOTFILES_DIR/ fetch origin --prune
git --git-dir=$DOTFILES_DIR/ --work-tree=$HOME branch --set-upstream-to=origin/$CURRENT_BRANCH $CURRENT_BRANCH

Create from scratch (optional)

This section is for anyone who wants to build their own dotfiles repo using the same git-dir + work-tree technique (not specifically this repo).

<details> <summary>Show from-scratch setup</summary>

Create the git dir and point work-tree at $HOME

DOTFILES_DIR=$HOME/git/dotfiles
mkdir -p "$DOTFILES_DIR"
git init "$DOTFILES_DIR"
git --git-dir="$DOTFILES_DIR" config core.worktree "$HOME"
git --git-dir="$DOTFILES_DIR" config --replace-all remote.origin.fetch "+refs/heads/*:refs/remotes/origin/*"

Add a safe default ignore policy (ignore everything, then un-ignore specific files)

touch "$HOME/.gitignore"
grep -qxF '/*' "$HOME/.gitignore" || printf '%s\n' '/*' >> "$HOME/.gitignore"
grep -qxF '!.gitignore' "$HOME/.gitignore" || printf '%s\n' '!.gitignore' >> "$HOME/.gitignore"

Start tracking files by un-ignoring paths in ~/.gitignore, then adding them

git --git-dir="$DOTFILES_DIR" --work-tree="$HOME" add .gitignore
git --git-dir="$DOTFILES_DIR" --work-tree="$HOME" commit -m "chore(dotfiles): initialise from scratch"

Optional: connect a remote and push

DOTFILES_REPO=git@github.com:your-user/dotfiles.git
dotfiles remote add origin "$DOTFILES_REPO"
dotfiles push -u origin HEAD

</details>

Setup YubiKey for `sudo`

macOS let's you use Touch ID for sudo but dem keyboards be expensive. Maybe you gots a YubiKey, this is how you set it up so you can touch your YubiKey instead of typing your password. The sudo/pam config is taken care of in flake.nix.

mkdir ~/.config/Yubico
pamu2fcfg > ~/.config/Yubico/u2f_keys

Add a second key if you like

pamu2fcfg -n >> ~/.config/Yubico/u2f_keys

Credit

Inspired by

StreakyCobra's comment on Hacker News for idea to avoid symlinks with bare repo
zwyx's blog post for Sublime Merge integration (historical reference; I now use LazyGit day-to-day)
Using a YubiKey (or other security key) for sudo via pam

Name	skill-creator-v2
Description	Create high-quality agent skills using a principle-driven approach. Use this when you need to create a new skill or improve an existing one, focusing on expertise transfer rather than mechanical instructions. This skill emphasizes research, synthesis, critique, and the four core truths of skill design.

skill-creator-v2

SKILL.md