📄 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.

JakubAndrysek/MkDoxy – Working With Multiple Branches Using `git worktree`.md

📄 MkDoxy – Working With Multiple Branches Using git worktree