merge

name: merge description: Use when the user asks to merge another branch into the current branch, pull upstream changes without rebasing, or resolve merge conflicts. argument-hint: "[target-branch] (defaults to master/main)"

input = $ARGUMENTS

Merge a target branch into the current feature branch.

Repo Identification

Submodule working directories hijack git rev-parse through ambient-directory inference. Resolve topology explicitly with -C <path> (or --git-dir / --work-tree) on every invocation for parent and each submodule.

Submodule Coordination

Merge submodules first so the parent merge references current pointers; push in the same order. After the parent merge completes, amend it to capture updated submodule HEADs:

git add {submodule} && git commit --amend -m "chore: merge {target} into {current-branch}"

Merge a submodule only when it has its own feature branch. Submodules on detached HEAD at a pinned commit are dependencies — leave them alone.

Use git merge origin/{target} (remote-tracking ref, not local branch).

Conflict Resolution

• Lockfiles, migrations, config, version bumps — accept the target version (latest agreed state), then regenerate lockfiles.
• Submodule pointer conflicts — accept the target's ref (git checkout MERGE_HEAD -- {submodule}); the correct ref is set after the submodule merge.
• Refactored-away code — target's removal wins; rewire to the new location/API.
• Additive conflicts (both sides add independent code) — keep both, then run the project's formatter/parser. Conflict boundaries leave orphan closing tags, duplicate brackets, and stray blocks that grep misses but a parser catches.

Partial survival: when a resolution keeps usage of a symbol, verify the declaration and import also survived. Grep the resolved file for every feature-side symbol before continuing.

Migration Reconciliation

Merge produces a merge commit but does NOT execute the target's new migrations against the local database. The DB version marker still holds the old revision — the app crashes at runtime on missing schema objects.

Re-chain: update the feature migration's parent revision to point to the target's chain tip. Update declared head tracking if the project tracks migration head outside alembic (check project CLAUDE.md/TOOLS.md).

Re-ID if non-monotonic. Re-pointing down_revision alone is not sufficient. If the feature's own revision ID is now ≤ any upstream ID in the new chain, the chain violates monotonic-timestamp rules and silently breaks any DB already stamped at that ID — alembic reports head, skips the inserted middle, app crashes on missing columns. Fix: generate a fresh date +%Y%m%d%H%M%S, update revision: str = … inside the file, rename the file to match, update project head tracking.

Verify chain: run alembic history and confirm revision IDs are non-decreasing along the chain.

Apply to local DB:

• DB at target's tip → only the feature migration needs applying.
• DB at feature's old pre-merge revision → stamp to the fork point (stamp moves the pointer without executing destructive down-migrations), then upgrade.
• DB stamped at the feature revision but upstream migrations between fork and feature were inserted later → re-running the feature crashes. Stamp back to the fork point, upgrade <last-upstream-rev> (not head), then stamp <feature-rev>.

Merge Commit Message

Pre-commit hooks often reject the default Merge branch 'X' into Y. Use conventional commit format and pass it explicitly:

git merge origin/{target} -m "chore: merge {target} into {current-branch}"

Same format for follow-up git commit after staging conflict resolutions. Notable decisions go in the commit body.

Execution

Announce the merge plan before starting — repos involved, divergence (commits ahead/behind), target branch. Invoking /merge is intent to push; no confirmation needed after the plan. Run /qg from each repo's working directory before pushing.

Report: repos merged, commits integrated, conflicts resolved, migration reconciliation, gate results.