Skip to content

Link a worktree primer article from the Concepts section #41

Description

@leogdion

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.

Metadata

Metadata

Assignees

No one assigned

    Labels

    No labels
    No labels

    Type

    No type

    Projects

    No projects

    Milestone

    No milestone

    Relationships

    None yet

    Development

    No branches or pull requests

    Issue actions