Document that add writes to the remote, and add --no-push

[leogdion]

Merge order: 3 of 6, into v1.0.0-integration.

Closes #25.

The problem

git trees add always finishes by calling track, which runs
git push -u origin HEAD when the branch is absent on the remote. A
local-feeling command therefore performs a network write and creates a public
branch, with no prompt and no mention in the docs.

The README documented the failure case ("if that push/upstream setup fails,
add exits nonzero") but never the success case. Pushing to a shared repo can
fire CI, send notifications, or publish a branch name that leaks a customer or an
embargo. Anyone without push rights just gets a confusing failure.

What changed

The default stays — parallel coding agents need an upstream, which is the whole
point. What changes is that it is stated, and it can be turned off.

Docs. The add section now leads with a callout that add writes to the
remote and what that costs; track says the same; the Environment table gains
TREES_NO_PUSH; usage gains a note.

--no-push on add and track. Sets the upstream when origin/<branch>
already exists; otherwise leaves it unset and prints the exact command to run.
Exit status stays 0 — not setting an upstream is the requested outcome, not a
failure. This matters because cmd_add calls cmd_track "$dir" >&2 || return 1,
so a nonzero return would fail the whole add.

TREES_NO_PUSH, any non-empty value, for setups that want it off globally.

No prompt — that would break the non-interactive agent workflow this tool exists
for.

cmd_track now parses options instead of taking a bare positional, so
track [path] [--no-push] works in either order and rejects unknown options and
extra arguments.

Verified

bash -n and shellcheck -s bash clean. Against a file:// fixture:

Check	Result
add nopush --no-push, remote branch absent	origin/nopush not created, upstream unset, push command printed, exit 0
add already-there --no-push, remote branch present	upstream still origin/already-there
TREES_NO_PUSH=1 add envnp	origin/envnp not created, exit 0
add feature-x / add brandnew, no flag	upstreams origin/feature-x / origin/brandnew; origin/brandnew is created — default unchanged
track nopush --no-push, track --no-push nopush2	both accepted
track --bogus, track a b	rejected with distinct errors
add pp --no-push --print-path	stdout is only the path

Full smoke block run locally end to end.

Conflicts to expect

cmd_add's option loop is adjacent to #36's branch-name validation (different
hunks — should merge clean). The README add/track sections are separate from
#38's quickstart and install edits, but #38 adds a Prerequisites section that
mentions forge auth for pushing; land that line once, in whichever merges second.

🤖 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: 7316ad11-a3a9-42aa-b951-0a88da88a1d3

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 add-no-push

---

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]

is there a way to set the tracking branch?

No. cmd_track hardcodes origin/$br — same remote, same name — and nothing exposes an arbitrary upstream. origin is hardcoded throughout, which follows from the layout assuming a single remote.

Per your call, no code or README change; recorded in AGENTS.md (fbf37cd) as a deliberate constraint rather than an oversight, with the trap for anyone adding --upstream later: add calls cmd_track unconditionally, so a flag that isn't threaded through cmd_add would silently overwrite the caller's choice.

Worth noting the escape hatch already works — track returns early once any upstream is set, so git branch --set-upstream-to=<whatever> sticks and track won't fight it.