Skip to content

Commit 03f1a7b

Browse files
docs: Update Git Worktrees documentation to use placeholder for default branch reference
1 parent 25f164d commit 03f1a7b

1 file changed

Lines changed: 20 additions & 5 deletions

File tree

src/docs/Ways-of-Working/Git-Worktrees.md

Lines changed: 20 additions & 5 deletions
Original file line numberDiff line numberDiff line change
@@ -9,22 +9,22 @@ All repositories are set up as **bare clones with worktrees**. This enables para
99
| Only one branch checked out at a time | Each issue gets its own worktree — parallel by default |
1010
| Switching branches requires clean state | Worktrees are independent — no stashing or committing WIP |
1111
| Agent work blocks human work on same repo | Different worktrees, no interference |
12-
| Default branch gets dirty during development | `main/` worktree is always a clean reference |
12+
| Default branch gets dirty during development | `<default>/` worktree is always a clean reference |
1313

1414
## Repository layout
1515

1616
```text
1717
<repo-root>/
1818
├── .bare/ # bare git data (the actual repository)
1919
├── .git # file containing: gitdir: ./.bare
20-
├── main/ # worktree: default branch (always clean, never worked in directly)
20+
├── <default>/ # worktree: default branch (always clean, never worked in directly)
2121
├── 42-add-pagination/ # worktree: issue #42 in progress
2222
└── 99-fix-null-ref/ # worktree: issue #99 in progress
2323
```
2424

2525
- **`.bare/`** — the shared git object store. All worktrees share this.
2626
- **`.git`** — a file (not a directory) that points git tooling to `.bare/`.
27-
- **`main/`** — the default branch worktree. Kept as a clean reference. Used for diffing, reading docs, running comparisons. Never directly committed to.
27+
- **`<default>/`** — the default branch worktree (e.g. `main` or `master`). Kept as a clean reference. Used for diffing, reading docs, running comparisons. Never directly committed to.
2828
- **`<N>-<slug>/`** — one worktree per issue in flight. Named by issue number and a short slug. Branch name matches the folder name.
2929

3030
## Remotes
@@ -70,8 +70,15 @@ git -C .bare config remote.origin.fetch '+refs/heads/*:refs/remotes/origin/*'
7070
# Fetch remote branches
7171
git -C .bare fetch origin
7272
73+
# Determine the default branch
74+
$defaultBranch = git -C .bare symbolic-ref HEAD | ForEach-Object { $_ -replace 'refs/heads/', '' }
75+
7376
# Create the default branch worktree
74-
git -C .bare worktree add ../main main
77+
git -C .bare worktree add "../$defaultBranch" $defaultBranch
78+
79+
# Set upstream tracking (prevents "Publish Branch" prompt in VS Code)
80+
git -C .bare config "branch.$defaultBranch.remote" origin
81+
git -C .bare config "branch.$defaultBranch.merge" "refs/heads/$defaultBranch"
7582
```
7683

7784
> The [Checkout-GitHubRepo](https://github.com/MariusStorhaug/.dev/blob/main/.github/Checkout-GitHubRepo.ps1) script automates this for all repositories.
@@ -80,7 +87,12 @@ git -C .bare worktree add ../main main
8087

8188
```powershell
8289
# From the repo root (where .bare/ lives)
83-
git -C .bare worktree add ../42-add-pagination -b 42-add-pagination main
90+
$defaultBranch = git -C .bare symbolic-ref HEAD | ForEach-Object { $_ -replace 'refs/heads/', '' }
91+
git -C .bare worktree add ../42-add-pagination -b 42-add-pagination $defaultBranch
92+
93+
# Set upstream tracking (prevents "Publish Branch" prompt in VS Code)
94+
git -C .bare config branch.42-add-pagination.remote origin
95+
git -C .bare config branch.42-add-pagination.merge refs/heads/42-add-pagination
8496
8597
# Open in VS Code
8698
code 42-add-pagination
@@ -94,6 +106,9 @@ Then follow the normal Implement flow: initial commit → push → draft PR →
94106
# Remove the worktree
95107
git -C .bare worktree remove 42-add-pagination
96108
109+
# Delete the local branch ref
110+
git -C .bare branch -D 42-add-pagination
111+
97112
# Prune if needed (removes stale worktree references)
98113
git -C .bare worktree prune
99114
```

0 commit comments

Comments
 (0)