wado-lang/wado / .claude/skills/git-upstream-sync
git-upstream-sync
VerifiedThe only way to merge origin/main into a branch, conflicts or not. Use it every time main comes in — a PR reported conflicting or DIRTY, a branch behind origin/main, a CI failure to reproduce on the merged tree. Never run `git merge origin/main` or `git pull origin main` by hand.
| File | Kind | Size |
|---|---|---|
| SKILL.md | skill md | 3.5 KB |
SKILL.md
View on GitHub---
name: git-upstream-sync
description: The only way to merge origin/main into a branch, conflicts or not. Use it every time main comes in — a PR reported conflicting or DIRTY, a branch behind origin/main, a CI failure to reproduce on the merged tree. Never run `git merge origin/main` or `git pull origin main` by hand.
---
# Overview
Merge origin/main into the current branch. Follow every step whether or not the
merge conflicts: a clean merge still ends with the sanity check, except as step
4 says.
## Procedure
### 1. Fetch and merge with zdiff3
If the branch is on `origin`, pull it first: CI's `tidy` job may have pushed
`chore: tidy` onto it. If that pull conflicts, take it through steps 2 and 3,
then start again here, so `origin/main` is merged too. Then move the checked-out submodules to the pointers the
merge recorded, so the next `git add -A` does not stage a stale checkout.
```sh
b=$(git branch --show-current)
if git ls-remote --exit-code --heads origin "$b" > /dev/null; then
git pull --no-rebase origin "$b" || exit 1 # a conflict stops here
fi
git fetch origin main
git -c merge.conflictstyle=zdiff3 merge origin/main
git submodule update --recommend-shallow
```
### 2. If conflicts exist, commit them as-is
If the merge produces conflicts, **commit the conflict markers without resolving them first**. This records the raw conflict state in a dedicated commit, separate from the resolution.
```sh
git add -A
git diff --cached origin/main -- vendor
git commit -m "merge origin/main (conflicts unresolved)"
```
The `vendor` diff prints nothing unless the branch bumps a submodule itself.
Anything else is a stale checkout that `git add -A` staged, reverting main's
bump. Restore main's pointer for each such path before committing, and check
again after every `git add -A`, step 3's included:
```sh
git update-index --cacheinfo 160000,"$(git rev-parse origin/main:vendor/wasmtime)",vendor/wasmtime
```
### 3. Resolve conflicts
After committing the unresolved state:
1. Read each conflicted file and understand both sides of the conflict
2. Resolve conflicts **in code files** (remove conflict markers, choose correct code)
3. For **generated files** (golden fixtures, generated parsers, …) that conflict,
**regenerate them** by re-running their generator and commit the fresh output —
do not hand-resolve the markers or defer them (see "Generated files" below)
4. Stage and commit the resolution:
```sh
git add -A
git diff --cached origin/main -- vendor # as in step 2
git commit -m "resolve merge conflicts"
```
### 4. Run `mise run test` for sanity check
CI applies clippy and format, so a quick sanity check is sufficient.
The one exception is a merge whose only conflict is `benchmark/fuel.json`.
Regenerate it with `mise run update-baselines`, commit that as the resolution,
and skip the tests.
## Important
- Always use `-c merge.conflictstyle=zdiff3` so the merge base is visible in conflict markers (with zealous zdiff3 reducing noise)
- Always commit the unresolved conflicts first, then resolve in a separate commit — this preserves a clear record of what the conflicts looked like vs how they were resolved
- Do NOT squash the two commits together
## Generated files
- **Always regenerate golden / generated files and commit.**
Re-run the generator (do not hand-resolve the markers) and commit its output.
Do not skip them or defer them to `on-task-done` / CI.
- **Never silently discard generated output** (e.g. `git restore` to clean the
tree or quiet a hook). Commit it, or ask. Discarding generated work without
asking is always wrong.
Related skills
| Skill | Stars | Updated | Works with | Status | Install |
|---|---|---|---|---|---|
| receiving-code-reviewobra/superpowersUse when receiving code review feedback, before implementing suggestions, especially if feedback seems unclear or technically questionable - requires technical rigor and verification, not performative agreement or blind implementation | Stars: 322k | Updated | Claude CodeCodex | Verified | Install |
| requesting-code-reviewobra/superpowersUse when completing tasks, implementing major features, or before merging to verify work meets requirements | Stars: 322k | Updated | Claude CodeCodex | Verified | Install |
| using-git-worktreesobra/superpowersUse when starting feature work that needs isolation from current workspace or before executing implementation plans - ensures an isolated workspace exists via native tools or git worktree fallback | Stars: 322k | Updated | Claude CodeCodex | Verified | Install |
| verification-before-completionobra/superpowersUse when about to claim work is complete, fixed, or passing, before committing or creating PRs - requires running verification commands and confirming output before making any success claims; evidence before assertions always | Stars: 322k | Updated | Claude CodeCodex | Verified | Install |