Branching, Merging, and Conflicts

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.

Branch management

poly branch list                   # all branches (--archived for soft-deleted ones)
poly branch current                # current branch + its parent
poly branch create <name>          # create + switch; branches from main's latest state
poly branch switch <name>          # requires a clean tree (--force discards local changes)
poly branch switch <name> --keep-files  # track <name> without touching files; next push sends them there
poly branch switch <name> --create --from main --keep-files  # same, creating <name> from main if missing
poly branch rename <new-name>
poly branch delete [<name>]        # main cannot be deleted
poly branch restore <branch_id>    # un-archive; IDs from poly branch list --archived
poly branch history                # branches merged into the current branch

Semantics that matter:

• create 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.
• Branches exist on the platform, not just locally — teammates can switch to yours, and the web UI can edit it while you work.
• 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.

Hotfix branches from a deployed environment

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.

How pull merges

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:

<<<<<<<
your local version
=======
the incoming remote version
>>>>>>>

While 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.

Merging a branch

poly branch merge 'Merge message'       # message required when merging into main

A 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.

Resolving merge conflicts

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):

[
  { "path": ["topics", "Booking", "content"], "strategy": "theirs" },
  { "path": ["agent_settings", "rules", "value"], "strategy": "theirs", "value": "Custom resolved content" },
  { "path": ["flows", "main_flow", "steps", "greet", "prompt"], "strategy": "ours" }
]

path 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.

Syncing with the parent branch

poly branch sync                        # bring the parent's newer changes into this branch

Needs a checkout with no unpushed changes; a clean sync pulls the updated branch. On conflict it exits non-zero with the same table, and takes the same --interactive and --resolutions routes as a merge ("ours" is the parent, "theirs" the branch). As an agent: poly branch sync --json, then re-run with --resolutions.

Sharing changes for review

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
poly review create                                  # local vs remote
poly review create --before main --after my-feature # any two branches/versions
poly review list                                    # open past gists
poly review delete --id <gist_id>

Habits that avoid trouble

• Pull before starting work so your base is recent and conflicts stay small.
• Keep branches small and single-purpose — easier to review and merge.
• Keep resource names stable; references point at resources by name.
• Check poly branch status before merging to know in advance whether it's clean.