merge-main

Follow these steps to merge the latest changes from the default branch into the current branch.

Note: This skill supports repositories whose default branch is named either main or master. The instructions below use the placeholder <default> to refer to whichever name applies.

0. Detect the default branch

Try the local ref first (fast, no network):

git symbolic-ref refs/remotes/origin/HEAD 2>/dev/null | sed 's|refs/remotes/origin/||'

If that returns main or master, use it. Otherwise fall back to querying the remote:

git remote show origin | sed -n 's/.*HEAD branch: //p'

Store the result and substitute it for every occurrence of <default> in the remaining steps.

If neither command returns main or master, check whether origin/main or origin/master exists:

git branch -r | grep -E 'origin/(main|master)$'

Use whichever exists. If both exist, prefer main. If neither exists, stop and inform the user.

1. Preflight checks

a. Determine the currently checked out branch. If it is <default>, stop and inform the user — do not merge <default> into itself.

b. Check for uncommitted changes (staged or unstaged) by running git status --porcelain. If the output is non-empty, stash them with git stash push -m "merge-main: auto-stash" and remember to pop them at the end.

2. Fetch and merge

a. Run git fetch origin <default> to get the latest remote changes.

b. Run git merge origin/<default> --no-edit.

c. If the merge completes cleanly with no conflicts, skip to step 4.

3. Resolve conflicts (only if the merge produced conflicts)

a. List all conflicted files with git diff --name-only --diff-filter=U.

b. For each conflicted file:

• Read the file and understand both sides of the conflict.
• Determine the correct resolution by understanding the intent of both changes.
• Edit the file to resolve the conflict, removing all conflict markers (<<<<<<<, =======, >>>>>>>).
• Stage the resolved file with git add <file>.

c. After all conflicts are resolved, finalize the merge with git commit --no-edit.

4. Review default branch changes for applicability

a. Get the list of files changed on the current branch vs origin/<default> using git diff --name-only origin/<default>...HEAD (the three-dot diff shows what the branch introduced).

b. Get the list of files changed on <default> since the branch's merge-base using git diff --name-only $(git merge-base HEAD origin/<default>)..origin/<default>.

c. Look for overlap or related files between these two lists — for example, if the branch modified a function and <default> changed how that function is called elsewhere, or if <default> introduced patterns/conventions that the branch's new files should follow.

d. If you find changes on <default> that are relevant to the branch's files (e.g., API changes, renamed imports, updated patterns, new shared utilities), apply those adjustments to the branch's files. Commit these as a separate commit with a descriptive message.

e. If nothing needs adjustment, move on.

5. Restore and push

a. If changes were stashed in step 1b, run git stash pop to restore them. If the pop fails due to conflicts, run git checkout --theirs . or manually resolve the stash conflicts, then run git stash drop to clean up the stash entry. Do not commit the restored stash — leave those as uncommitted working changes.

b. Push the branch to the remote with git push.

c. If the push is rejected (e.g., due to a force-push or diverged history), do not force push. Inform the user and ask how to proceed.

6. Summary

a. Provide a brief summary: how many commits were merged, whether conflicts were resolved, and whether any applicability adjustments were made.