Skip to main content

/kosuke:sync-branch

/kosuke:sync-branch brings your branch up to date with the project's Target Branch. The agent merges, resolves conflicts by what each side meant, and checks that the project still builds and runs. It asks you only when the code cannot settle a conflict, for example when both sides changed the same thing for the same reason, or when their dependency changes are incompatible. The Sync button runs this skill, and Sync with the Target Branch covers when the button appears.

When to use it​

Run it when the branch is behind its Target Branch or its pull request has conflicts. You can also run it before a review, so reviewers see the change against the latest code.

Run it​

Type /kosuke:sync-branch, or $kosuke:sync-branch in a Codex session.

ArgumentWhat it doesDefault
--target-branch <branch>Overrides the branch to sync with. The button passes a non-default project Target Branch only before a pull request opens.The open pull request's base, then the project's Target Branch, then GitHub's default branch.
/kosuke:sync-branch
/kosuke:sync-branch --target-branch release/2.4
/kosuke:sync-branch rebase instead of merging

What it does​

  1. It checks whether the branch is behind. When it already has everything, the agent says so and stops, and your work stays as it was.
  2. It sets your uncommitted work aside. With the Commits preference on Automatic, it commits that work. With Manual, it stashes the work and restores it at the end.
  3. It merges the Target Branch in. It rebases only when you ask, or when the branch was never pushed and has no pull request.
  4. It resolves each conflict by reading what each side changed and why. When both sides changed the same thing for the same reason, it collects every such conflict into one Clarification. For each one you keep this branch's version, take the Target Branch's, or describe another resolution.
  5. It keeps both sides' migrations and dependency changes. Where your branch's migrations collide with the Target Branch's in order or name, it carries their intent into a new migration that runs after the Target Branch's. It regenerates the lockfile with the project's own package manager, and asks you when the dependency changes are incompatible.
  6. It runs the project's own checks, such as the type check, lint, build and tests, and fixes what the merge broke.
  7. It re-runs the project's setup and restarts its services.

Some merged code needs an environment variable or a service added to the project settings after the session started. The agent tells you when that happens, because it takes a new chat session.

What you get​

  • After a merge, a merge commit named chore: sync with <target>, or chore: sync with <target> (resolved N conflicts). The agent makes this commit whatever your Commits preference. A rebase makes no merge commit.
  • With Commits on Automatic, the merge is pushed and the branch is no longer behind. With Manual, the merge commit waits for you. On an Active session, press Push in the chat footer to publish it. An Under Review session has no footer, so press Resume first.
  • A reply that lists what came in and how each conflict was resolved. It also covers the migrations and dependencies, the checks it ran and the state of the app.

Set the Commits preference in Your account and preferences.

Limits​

  • It never takes one side of a conflict wholesale or deletes work to make a conflict go away.
  • It never discards your uncommitted changes.
  • It never force-pushes a branch with an open pull request unless you ask for exactly that.
  • It never edits a migration that is already on the Target Branch.

Next steps​