Load poly-adk-workflow first for where branching sits in the build loop. The one rule that shapes everything: you cannot work on main — branch diff, merge, sync, tag, and untag all refuse to run there.
poly branch list # all branches (--archived for soft-deleted ones)\npoly branch current # current branch + its parent\npoly branch create <name> # create + switch; branches from main's latest state\npoly branch switch <name> # requires a clean tree (--force discards local changes)\npoly branch rename <new-name>\npoly branch delete [<name>] # main cannot be deleted\npoly branch restore <branch_id> # un-archive; IDs from poly branch list --archived\npoly branch history # branches merged into the current branch\nSemantics that matter:
\ncreate carries uncommitted local work onto the new branch; switch refuses to move with uncommitted changes and replaces local files with the target branch's state. Started editing on main by accident? branch create alone recovers it — nothing is lost.poly status/poly diff show unpushed local edits; poly branch status/poly branch diff show everything since the branch was created. Use the branch-level pair before merging. poly branch status also says whether the branch has diverged — i.e. whether it will merge cleanly.poly branch create my-hotfix --env live snapshots the deployed environment into a fresh branch (also sandbox, pre-release). Use with caution: it overwrites your local project with the deployed state, and merging that branch back to main can roll back changes made after the snapshot. It fails on uncommitted local changes unless --force.
poly pull never blind-overwrites. It three-way merges, line by line, between base (state at your last pull/push, tracked in _gen/.agent_studio_config), local (your disk, including uncommitted edits), and incoming (the remote branch). Files are re-serialized to canonical form first, so formatting and key-order differences never conflict — only real content changes do. A file deleted locally stays deleted.
Conflicts are written into files with unlabelled markers — unlike Git, there are no branch names:
\n<<<<<<<\nyour local version\n=======\nthe incoming remote version\n>>>>>>>\nWhile any marker remains, status, diff, validate, and push all refuse to run. poly pull lists every conflicted file; edit each to the content you want, delete the markers, then continue. Escape hatches: poly pull -f discards all local work and takes the remote (confirm with the user first — it also deletes local resources missing from the remote); poly pull --format formats all three sides first to reduce spurious conflicts.
poly branch merge 'Merge message' # message required when merging into main\nA clean merge completes immediately and switches your checkout to the parent branch. Merging into main deploys to sandbox automatically. The web UI's Merge button hits the same endpoint — identical result.
On conflict the command exits non-zero and prints a table per conflicting field: Path (e.g. topics > Booking > content), Base / Ours / Theirs values, the auto-merged value, and whether it's auto-mergeable. Two resolution routes:
--interactive / -i — walks each conflict: accept the auto-merge, pick ours (parent) / theirs (branch) / base, or edit in $EDITOR. Terminal-only; incompatible with --json.--resolutions <source> — the non-interactive route, so the one to use as an agent. A JSON array (file path, inline string, or - for stdin):[\n { \"path\": [\"topics\", \"Booking\", \"content\"], \"strategy\": \"theirs\" },\n { \"path\": [\"agent_settings\", \"rules\", \"value\"], \"strategy\": \"theirs\", \"value\": \"Custom resolved content\" },\n { \"path\": [\"flows\", \"main_flow\", \"steps\", \"greet\", \"prompt\"], \"strategy\": \"ours\" }\n]\npath matches the conflict table's Path column; strategy is \"ours\", \"theirs\", or \"base\"; a custom value is only honored with \"theirs\". Workflow: run poly branch merge --json once to surface the conflicts, build a resolutions file covering each path, re-run with --resolutions. Confirm resolution choices with the user when the right answer isn't obvious — both sides are real work.
Both review commands publish a private GitHub Gist (one .diff file per changed resource) so reviewers don't need filesystem access. Requires a GitHub token in the environment.
poly branch review # this branch since creation\npoly review create # local vs remote\npoly review create --before main --after my-feature # any two branches/versions\npoly review list # open past gists\npoly review delete --id <gist_id>\npoly branch status before merging to know in advance whether it's clean.