# Merge Main

> Fetch and merge the base branch (usually main) into the current feature branch, handling conflicts and pushing. Use when the user says "merge main", "merge in main", "merge base branch", "update from main", "pull in main", "sync with main", "merge main into this branch", "update branch from main", or any variant involving merging the default branch into the current working branch.

- Skill: `cboone/merge-main` (Agent Skill)
- Install (CLI): `npx skillmds@latest add cboone/merge-main`
- Raw SKILL.md: https://api.skillmd.com/api/skills/cboone/merge-main/raw
- Safety review: pending
- Works with: Claude Code, Claude.ai, OpenAI Codex
- Category: Coding & Dev Tools
- Author: cboone (https://skillmd.com/u/cboone)
- Updated: 2026-09-17
- Page: https://skillmd.com/skills/cboone/merge-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`)

## 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.
   - **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.