From 885a7d610aefcb037e3aea73ecc82f763b1bcfef Mon Sep 17 00:00:00 2001 From: Marius Storhaug Date: Mon, 13 Jul 2026 12:36:32 +0200 Subject: [PATCH 1/2] =?UTF-8?q?=F0=9F=93=96=20[Docs]:=20Emphasize=20parall?= =?UTF-8?q?el=20agentic=20work=20in=20the=20Git=20Worktrees=20page?= MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit --- src/docs/Ways-of-Working/Git-Worktrees.md | 10 ++++++++++ 1 file changed, 10 insertions(+) diff --git a/src/docs/Ways-of-Working/Git-Worktrees.md b/src/docs/Ways-of-Working/Git-Worktrees.md index e0f6efa..b84f0da 100644 --- a/src/docs/Ways-of-Working/Git-Worktrees.md +++ b/src/docs/Ways-of-Working/Git-Worktrees.md @@ -9,6 +9,16 @@ Git worktrees are how [agentic development](Agentic-Development.md) is implement All repositories are set up as **bare clones with worktrees**. Each piece of work gets its own worktree — an independent working directory for one branch — so parallel work never collides. +## Why this matters: working agentically in parallel + +The reason this layout is the default — not the occasional convenience it is in most projects — is **parallelism**. [Agentic development](Agentic-Development.md) does not proceed one issue at a time. A single developer can have several agents working at once, each on a different issue, alongside their own hands-on changes. Worktrees are what make running many streams at once safe instead of chaotic: + +- **One worktree per issue, one agent per worktree.** Each agent gets its own working directory, its own branch, and its own uncommitted state. Two agents never write to the same checkout, so their edits cannot corrupt one another. +- **No stashing, no branch-switching, no waiting.** Because the worktrees are independent, the agent finishing issue #42 never disturbs the one still working issue #99 — and neither touches the clean `/` reference you read from. Nobody has to reach a clean tree before anyone else can move. +- **Fan out, then integrate.** A batch of independent issues can be started together — one worktree each — worked concurrently, and merged back one at a time through the normal [branch-and-PR flow](Branching-and-Merging.md) as each finishes. + +In a single ordinary clone the opposite is forced: one branch checked out at a time, every human and agent contending for the same files, constant stashing and switching. Worktrees turn "several issues at once" from a hazard into the default working mode — which is what makes local agentic development practical at all. + ## Why worktrees | Problem with traditional clones | How worktrees solve it | From fbabf35135d170c9f964d6aff03fa5af63326f9a Mon Sep 17 00:00:00 2001 From: Marius Storhaug Date: Mon, 13 Jul 2026 12:39:50 +0200 Subject: [PATCH 2/2] =?UTF-8?q?=F0=9F=93=96=20[Docs]:=20Fix=20missing=20pr?= =?UTF-8?q?eposition=20(working=20on=20issue=20#99)?= MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit --- src/docs/Ways-of-Working/Git-Worktrees.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/src/docs/Ways-of-Working/Git-Worktrees.md b/src/docs/Ways-of-Working/Git-Worktrees.md index b84f0da..1087f45 100644 --- a/src/docs/Ways-of-Working/Git-Worktrees.md +++ b/src/docs/Ways-of-Working/Git-Worktrees.md @@ -14,7 +14,7 @@ All repositories are set up as **bare clones with worktrees**. Each piece of wor The reason this layout is the default — not the occasional convenience it is in most projects — is **parallelism**. [Agentic development](Agentic-Development.md) does not proceed one issue at a time. A single developer can have several agents working at once, each on a different issue, alongside their own hands-on changes. Worktrees are what make running many streams at once safe instead of chaotic: - **One worktree per issue, one agent per worktree.** Each agent gets its own working directory, its own branch, and its own uncommitted state. Two agents never write to the same checkout, so their edits cannot corrupt one another. -- **No stashing, no branch-switching, no waiting.** Because the worktrees are independent, the agent finishing issue #42 never disturbs the one still working issue #99 — and neither touches the clean `/` reference you read from. Nobody has to reach a clean tree before anyone else can move. +- **No stashing, no branch-switching, no waiting.** Because the worktrees are independent, the agent finishing issue #42 never disturbs the one still working on issue #99 — and neither touches the clean `/` reference you read from. Nobody has to reach a clean tree before anyone else can move. - **Fan out, then integrate.** A batch of independent issues can be started together — one worktree each — worked concurrently, and merged back one at a time through the normal [branch-and-PR flow](Branching-and-Merging.md) as each finishes. In a single ordinary clone the opposite is forced: one branch checked out at a time, every human and agent contending for the same files, constant stashing and switching. Worktrees turn "several issues at once" from a hazard into the default working mode — which is what makes local agentic development practical at all.