Merge Main

---
name: merge-main
description: >-
  Merge the base branch into the current branch, resolve conflicts, and push.
  Use for "merge main" or "sync with main"; to rebase, use rebase-onto-main.
---

# Merge Main

Fetch and merge the repository's base branch into the current feature branch.

## Options

The user may provide these options inline:

- **--base `<branch>`**: Override the auto-detected base branch (e.g., `--base develop`)

## Skill dependencies

- **Required:** None
- **Optional:** `commit`

## Workflow

### 1. Pre-Flight Checks

Run these commands in parallel to understand the current state:

```bash
# Check for uncommitted changes
git status

# Detect the repository's default branch
gh repo view --json defaultBranchRef -q '.defaultBranchRef.name'

# Confirm which branch we are on
git branch --show-current
```

If `--base <branch>` was specified, use that value instead of the detected default branch.

**If `gh` is not available**, fall back to detecting the default branch with:

```bash
git remote show origin | grep 'HEAD branch' | sed 's/.*: //'
```

**If the current branch is the default branch itself**, warn the user that merging the base branch into itself is a no-op and stop.

### 2. Handle Uncommitted Changes

If `git status` shows uncommitted changes (staged or unstaged):

1. Warn the user that there are uncommitted changes.
1. Ask whether to:
   - **Stash**: Run `git stash` before proceeding, then `git stash pop` after the merge completes.
   - **Commit first**: Invoke the `/commit` skill, then continue with the merge. `commit` is an optional dependency: if it is not installed, leave this choice out and tell the user why, so they can commit by hand, or install `commit`, before running this skill again.
   - **Abort**: Stop without doing anything.

### 3. Fetch and Merge

```bash
git fetch origin <default-branch>
git merge origin/<default-branch>
```

Where `<default-branch>` is the detected or overridden base branch name.

### 4. Handle Merge Result

#### Clean Merge

If the merge completes without conflicts:

1. Report success.
1. Show a summary of what was merged:

```bash
git log HEAD@{1}..HEAD --oneline
```

#### Already Up to Date

If git reports "Already up to date.", report that the branch is already current with the base branch and stop.

#### Conflicts

If the merge produces conflicts, proceed to the conflict resolution workflow below.

### 5. Conflict Resolution

When merge conflicts occur:

1. **List conflicted files**:

```bash
git diff --name-only --diff-filter=U
```

1. **Resolve each conflicted file**:
   - Read the file and examine the conflict markers (`<<<<<<<`, `=======`, `>>>>>>>`).
   - Use the surrounding code context, the intent of both sides, and the project's conventions to determine the correct resolution.
   - For trivial conflicts (whitespace, import ordering, adjacent non-overlapping changes), resolve automatically.
   - For non-trivial conflicts where the correct resolution is ambiguous, show the user both sides and ask which to keep or how to combine them.

1. **Stage resolved files**:

```bash
git add <resolved-file>
```

1. **Complete the merge commit** (GPG signed):

```bash
git commit -S --no-edit
```

This uses the default merge commit message generated by git. If the user wants a custom message, they can specify it.

### 6. Post-Merge Steps

After a successful merge (with or without conflict resolution):

1. **Lockfile changes**: If any lockfiles changed during the merge (e.g., `package-lock.json`, `yarn.lock`, `pnpm-lock.yaml`, `go.sum`, `Gemfile.lock`, `poetry.lock`, `Cargo.lock`, `composer.lock`), suggest running the appropriate install command:
   - `package-lock.json` -> `npm install`
   - `yarn.lock` -> `yarn install`
   - `pnpm-lock.yaml` -> `pnpm install`
   - `go.sum` -> `go mod tidy`
   - `Gemfile.lock` -> `bundle install`
   - `poetry.lock` -> `poetry install`
   - `Cargo.lock` -> `cargo build`
   - `composer.lock` -> `composer install`

1. **Push**:

```bash
git push
```

If the branch has no upstream, use:

```bash
git push -u origin HEAD
```

### 7. Stash Recovery

If changes were stashed in step 2, pop the stash after the merge completes:

```bash
git stash pop
```

If the stash pop produces conflicts, warn the user and list the conflicted files.

## Error Handling

- **On the default branch**: Warn that merging the base branch into itself is a no-op and stop.
- **No remote configured**: Report the error and stop.
- **Merge aborted by user**: Clean up with `git merge --abort`.
- **Fetch failure** (network issues, authentication): Report the error clearly and stop.
- **Stash pop conflicts**: Warn the user and list conflicted files so they can resolve manually.