The ## Concepts section added in #38 defines five terms — worktree, bare store,
container, gitdir pointer, upstream — in about a paragraph each. That is the
right depth for a README: enough to read the rest of the page without getting
lost.
It is not enough for someone genuinely new to git worktree, and the section
can't be, without turning the README into a tutorial. The things it deliberately
leaves out:
- Why you would want several checkouts at once, rather than stashing and
switching. The parallel-coding-agent case is the motivating one for this tool
but it is not the only one.
- How the shared object store changes the cost model — the tenth worktree costs
a checkout, not a tenth copy of the history, and that is the whole reason the
layout is practical.
- What bare repo + worktrees buys over just running
git clone twice: one
fetch, one set of refs, no drift between copies.
- The failure modes that confuse people first: a container root where
git status reports fatal: this operation must be run in a work tree, and
a new branch silently inheriting its base ref's upstream.
Write that up as an article and link it from Concepts as further reading.
Blocked on the article existing — this issue tracks the link, not the prose.
The
## Conceptssection added in #38 defines five terms — worktree, bare store,container, gitdir pointer, upstream — in about a paragraph each. That is the
right depth for a README: enough to read the rest of the page without getting
lost.
It is not enough for someone genuinely new to
git worktree, and the sectioncan't be, without turning the README into a tutorial. The things it deliberately
leaves out:
switching. The parallel-coding-agent case is the motivating one for this tool
but it is not the only one.
a checkout, not a tenth copy of the history, and that is the whole reason the
layout is practical.
git clonetwice: onefetch, one set of refs, no drift between copies.
git statusreportsfatal: this operation must be run in a work tree, anda new branch silently inheriting its base ref's upstream.
Write that up as an article and link it from Concepts as further reading.
Blocked on the article existing — this issue tracks the link, not the prose.