📄 MkDoxy – Working With Multiple Branches Using git worktree

This guide shows a clean setup for editing MkDoxy across multiple branches at once using git worktree.

Prerequisites

• Git 2.38+ recommended
• A root dev folder (examples use ~/code)

1) Clone the repository (primary working copy)

mkdir -p ~/code && cd ~/code
git clone [email protected]:JakubAndrysek/MkDoxy.git
cd MkDoxy

# Nice defaults
git config worktree.guessRemote true
git config fetch.prune true
git config remote.origin.prune true

Keep this primary copy on main and up to date.

2) Choose a worktree root

Create a sibling folder for all extra worktrees (not inside the repo):

mkdir -p ~/code/wt/mkdoxy

Example layout:

~/code/
  MkDoxy/
  wt/
    mkdoxy/
      feat/new-parser/
      fix/issue-123/
      pr/456/
      rel/v0.8.0/

3) Create worktrees

New feature branch from origin/main

cd ~/code/MkDoxy
git fetch origin
git worktree add ~/code/wt/mkdoxy/feat/new-parser -b feat/new-parser origin/main

Existing remote branch

git fetch origin
git worktree add ~/code/wt/mkdoxy/fix/issue-123 origin/fix/issue-123

PR review branch

git fetch origin pull/456/head:pr/456
git worktree add ~/code/wt/mkdoxy/pr/456 pr/456

Tag or release candidate

git fetch --tags
git worktree add ~/code/wt/mkdoxy/rel/v0.8.0 v0.8.0

4) Daily workflow

• Update primary:

  cd ~/code/MkDoxy
  git pull --rebase --autostash

• Work inside a worktree:

  cd ~/code/wt/mkdoxy/feat/new-parser
  git add -A
  git commit -m "feat(parser): initial block handling"
  git push -u origin feat/new-parser

• Open a PR on GitHub from that branch.

5) Maintenance

• List all worktrees:

  git worktree list

• Remove a finished worktree (clean dir):

  git worktree remove ~/code/wt/mkdoxy/feat/new-parser

• Prune stale metadata:

  git worktree prune

6) Tips & Gotchas

• A branch can be checked out in only one worktree at a time.
• Don’t put worktrees inside another Git repo.
• Hooks are shared (live in the main repo’s .git/hooks).
• For submodules, run git submodule update --init --recursive inside each worktree when needed.

7) Optional Git aliases

Add to ~/.gitconfig:

[alias]
  wt = worktree
  wtls = worktree list
  wtadd = !f() { git worktree add "$@"; }; f
  wtrm = !f() { git worktree remove "$@"; }; f

Usage:

git wtls
git wtadd ~/code/wt/mkdoxy/feat/new-parser -b feat/new-parser origin/main
git wtrm  ~/code/wt/mkdoxy/feat/new-parser

---

Happy hacking! With this layout, you can freely build, test, and compare branches of MkDoxy side-by-side without juggling stashes or re-checkouts.