Docs: a quickstart that works, a concepts primer, and honest install docs

[leogdion]

Merge order: 4 of 6, into v1.0.0-integration. Expect a README quickstart
conflict with #35 and an Install-section conflict with the release PR.

Closes #20, closes #24, closes #26, closes #29.

Four documentation issues grouped because all four edit README.md, three of
them within ~15 lines of each other.

#20 — the quickstart left a new user where git doesn't work

init then cd lands you in a directory with no worktree, so the next git
command fails with fatal: this operation must be run in a work tree. To a
novice that reads as "this tool broke my git". Compounding it, the layout diagram
was captioned "git trees init produces:" while showing a <branch-name>/
directory that only add ever creates.

The quickstart now includes the first worktree and says the intermediate state is
expected. The diagram is split into after-init and after-add.

#24 — "Requires bash 4+" was wrong

No bash-4-only features are used, and the shebang is #!/usr/bin/env bash, so on
macOS this usually resolves to /bin/bash 3.2 — meaning the stated requirement
was both wrong and wrong about the most likely platform. Replaced with an
accurate statement, plus a Prerequisites section covering git, bash, network
for init, and forge credentials.

#26 — no anchor for a reader new to git worktree

Added a Concepts section defining worktree, bare store, container, gitdir
pointer, and upstream. AGENTS.md.template said not to git checkout without
saying what to do instead — it now names git trees add <name>. This repo's
AGENTS.md now states that it is contributor guidance and that the template is a
product artifact for a different audience.

The fourth item in #26 — "--older-than reads as age-only" — is void: #35
removes clean.

#29 — install underspecified, uninstall broken for custom prefixes

./install.sh <dir> installs anywhere, but --uninstall only ever looked in
~/.local/bin and /usr/local/bin. A custom-prefix install could not be undone
by the tool that created it, and nothing said so. Now
./install.sh --uninstall [dir] takes the same destination, warns when it finds
nothing, and reports that it leaves ~/.config/git-trees/AGENTS.md behind.

The README now documents clone + install.sh as the full install, states that
curl skips the agents template (so the documented TREES_AGENTS_TEMPLATE default
points at a file you don't have) and tracks a moving main, and adds the PATH
step the curl path can't warn about.

The curl URL still points at main here — the release PR pins it to the tag, so
the README doesn't 404 in the window before v1.0.0 exists.

Verified

bash 3.2 claim, at runtime — not just bash -n. Under
GNU bash 3.2.57(1)-release: help, root, add feature-x, add brandnew,
add --print-path, track, list, list --json, clean, and the
outside-a-repo error all behave correctly. Upstreams came out origin/feature-x
and origin/brandnew — both AGENTS.md regressions hold on 3.2.

The quickstart, followed literally. After init: exactly .git,
AGENTS.md, trees-bare.git — the diagram matches disk. git status there
prints fatal: this operation must be run in a work tree, as the new text says.
After git trees add main && cd main, git status succeeds
(## main...origin/main). add feature-x then produces the sibling directory.

install.sh, against a redirected HOME so no real install was touched:

Case	Result
install to custom DEST	binary placed, template seeded, off-PATH warning
--uninstall with no dir, custom install present	reports "no git-trees found in …", suggests passing the dir, leaves it
--uninstall <same dir>	removed
default install → default --uninstall	removed
every uninstall	reports leaving ~/.config/git-trees/AGENTS.md

shellcheck -s bash git-trees install.sh clean.

🤖 Generated with Claude Code

[coderabbitai]

Important

Review skipped

Auto reviews are disabled on base/target branches other than the default branch.

Please check the settings in the CodeRabbit UI or the .coderabbit.yaml file in this repository. To trigger a single review, invoke the @coderabbitai review command.

⚙️ Run configuration

Configuration used: defaults

Review profile: CHILL

Plan: Pro Plus

Run ID: 1e022d4c-6d0d-4c27-b288-44f59313bc73

You can disable this status message by setting the reviews.review_status to false in the CodeRabbit configuration file.

Use the checkbox below for a quick retry:

• 🔍 Trigger review

✨ Finishing Touches

🧪 Generate unit tests (beta)

• Create PR with unit tests
• Commit unit tests in branch docs-and-install

---

Thanks for using CodeRabbit! It's free for OSS, and your support helps us grow. If you like it, consider giving us a shout-out.

❤️ Share

• X
• Mastodon
• Reddit
• LinkedIn

_{Comment @coderabbitai help to get the list of available commands.}

[leogdion]

Add a GitHub issue to link to a new article about working with work trees

[leogdion]

Filed as #41 — it covers why several checkouts beat stash-and-switch, the shared-object-store cost model, what bare+worktrees buys over cloning twice, and the two failure modes that confuse people first (the container root where git status refuses, and upstream inheritance). Blocked on the article existing, so the Concepts section is unchanged here; the issue tracks adding the link.