Branch merging

Merge a branch into its parent with poly branch merge, including interactive and pre-defined conflict resolution. On the new deployment system, merging a Branch into main publishes it to Live.

poly branch merge is the CLI-native counterpart to merging in the Agent Studio web UI. It brings everything you’ve changed on the current branch back onto its parent (main for a Branch, or the parent Branch for a Sub-branch). It surfaces any conflicts in a structured table and lets you resolve them either interactively or from a JSON file.

How the CLI maps to the new deployment system

main is the Live version on projects using the new deployment system. A branch is a Branch, cut from Live. A branch created from another branch is a Sub-branch.
poly branch merge merges into the parent. Merging a Branch into main publishes it to Live. Merging a Sub-branch merges it into its Branch.
poly branch sync is Sync. It pulls the parent’s changes into your branch. Run it before merging if the parent has moved on.
poly branch tag moves the current Branch to Staging (pre-release in the CLI). poly branch untag removes it.
poly deployments promote, and the old sequence of promoting from sandbox to pre-release to live, apply only to projects that have not yet moved to the new deployment system.
poly deployments rollback rolls Live back on new-system projects.

For the broader branching workflow (creating, switching, listing, deleting branches), see the poly branch section of the CLI reference. For the team-level guardrails around branching and merging, see Multi-user workflows and guardrails.

When to use it

You’ll typically reach for poly branch merge at the end of a feature loop:

Create a branch with poly branch create my-feature (see poly branch create).
Iterate locally, pushing with poly push (see Working locally).
Test with poly chat against the branch’s pushed state.
Merge back to main with poly branch merge '<message>', described on this page. On the new deployment system this publishes the Branch to Live.
On projects that have not yet moved to the new deployment system, promote the merged state with poly deployments promote.

You can also do this in Agent Studio. Open a Branch and click Publish in the top-right corner, or open a Sub-branch and click Merge. The CLI command and the UI hit the same platform endpoint, so the result is identical.

Basic usage

poly branch merge requires a merge message and merges the current branch into its parent (main for a Branch, or the parent Branch for a Sub-branch). Switch to the source branch first if you aren’t on it.

poly branch switch my-feature
poly branch merge 'Merge my-feature into main'

If the merge has no conflicts, the branch is merged immediately and the CLI automatically switches your local checkout to main. Run poly pull afterwards if you need to refresh local state.

Argument	Required	Description
`message`	yes	Merge commit message. Quote it if it contains spaces.
`--interactive`, `-i`	no	Resolve conflicts in an interactive prompt.
`--resolutions <source>`	no	Pre-defined resolutions as a JSON file path, inline JSON string, or `-` for stdin.
`--path <dir>`	no	Project base path. Defaults to the current working directory.
`--json`	no	Print a single JSON object on stdout (machine-readable).
`--verbose`	no	Show full error tracebacks for debugging.

Conflicts

If the merge has conflicts, the command prints a conflict table and exits with a non-zero status code. The table shows, for each conflicting field:

Path: the resource and field that conflicts (for example topics > Booking > content)
Base / Ours / Theirs: the original value and the two competing values
Auto-merged value: what the ADK would produce by line-merging the two sides
Auto-mergeable: whether the auto-merged value contains any unresolved markers

If every conflict is auto-mergeable and you want to accept the auto-merge, re-run the command with --interactive and accept the suggestions, or pre-populate --resolutions with the auto-merge values.

`--interactive` / `-i`

Interactive mode walks you through each conflict and asks how to resolve it. For every conflict you can:

accept the auto-merge (when available)
pick main (ours)
pick branch (theirs)
pick base (revert to the original value)
open the value in your $EDITOR or $VISUAL for free-form editing

After you’ve answered every conflict the merge is re-attempted automatically.

Set $EDITOR or $VISUAL before starting an interactive mergeInteractive mode shells out to your editor for multiline or long values. If neither variable is set it falls back to vi. Setting EDITOR=code --wait (or your editor of choice) in your shell profile makes the experience much smoother.

`--resolutions <source>`

Use --resolutions to supply pre-defined resolutions non-interactively. The source can be:

a path to a JSON file
a literal JSON string
- to read JSON from stdin

If the resolutions cover every conflict the merge proceeds without prompting. Combine --resolutions with --interactive to seed an interactive session. Pre-defined choices are applied automatically and you’ll only be prompted for the conflicts they don’t cover.

Resolution file format

--resolutions expects a JSON array of objects:

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

Field	Description
`path`	List of strings identifying the conflicted field. Match the `Path` column from the conflict table.
`strategy`	One of `"ours"` (keep `main`), `"theirs"` (keep branch), or `"base"` (revert to the original).
`value`	Optional custom value. Only honored with the `"theirs"` strategy.

You can capture the structure of a resolution file by running poly branch merge once to surface the conflicts, then writing a JSON file that addresses each path row.

After a successful merge

The CLI switches your local checkout to main.
Run poly pull if you need to refresh local state to match the post-merge main.
Run poly chat against main (which falls back to the sandbox environment) to smoke-test the merged result. On the new deployment system, merging a Branch into main publishes it to Live straight away, so test the Branch with poly chat before you merge.
On projects that have not yet moved to the new deployment system, follow up with poly deployments to promote the merged state to a live environment. On the new deployment system the merge has already published the Branch. If you need to undo it, poly deployments rollback rolls Live back.

Merging through the Agent Studio web UI

You can also merge through the Agent Studio interface:

Open the project in Agent Studio.
Open the Branch or Sub-branch.
Click Publish in the top-right corner for a Branch, or Merge for a Sub-branch.

The web UI surfaces the same conflicts as the CLI and lets you resolve them in the browser. Use whichever path fits your workflow. They hit the same platform endpoint, so there is no functional difference between them.

Troubleshooting

Symptom	Likely cause	Fix
`Merge message is required`	You ran `poly branch merge` with no message argument.	Pass a quoted message: `poly branch merge 'Describe the merge'`.
Conflict table appears and the command exits non-zero	One or more fields conflict between branch and `main`.	Re-run with `--interactive` or supply `--resolutions`.
`[Errno 22] Invalid argument` during interactive prompt	The shell isn’t a TTY (CI, scripts, non-interactive containers).	Run interactively, or use `--resolutions` with a pre-built JSON file.
Editor doesn’t open in interactive mode	`$EDITOR` and `$VISUAL` are unset.	Export one of them before running the merge.
Local changes block the merge	You have unpushed work on the source branch.	Run `poly push` first, or `poly revert` to discard.

Tests

Validate agent behavior with conversation tests before merging.

Tooling

IDE extensions and AI coding tools that integrate with the ADK workflow.

Multi-user workflows and guardrails

How branches, merges, and validation interact across a team.

Overview

Get started

Tutorials

Core concepts

Examples

Reference

Community

Legal

When to use it

Basic usage

Conflicts

`--interactive` / `-i`

`--resolutions <source>`

Resolution file format

After a successful merge

Merging through the Agent Studio web UI

Troubleshooting

Tests

Tooling

Multi-user workflows and guardrails

​When to use it

​Basic usage

​Conflicts

​--interactive / -i

​--resolutions <source>

​Resolution file format

​After a successful merge

​Merging through the Agent Studio web UI

​Troubleshooting

​Related references

Tests

Tooling

Multi-user workflows and guardrails

When to use it

Basic usage

Conflicts

`--interactive` / `-i`

`--resolutions <source>`

Resolution file format

After a successful merge

Merging through the Agent Studio web UI

Troubleshooting

Related references