merge-to-main

name	merge-to-main
description	Use when the user wants to commit local changes, sync with GitHub, and push. Triggers on "merge my changes", "push to remote", "commit and push", "merge into main", "sync local changes", "get my changes onto main", or any request to integrate local/branch work into main and push to GitHub.

Merge to Main

Commits local work, syncs with GitHub, pushes up.

Terminology: "local" = your machine. "remote" / "GitHub" = origin on GitHub.

Step 1: Assess state

rtk git status
rtk git branch -a
rtk git log --oneline -5
rtk git remote -v

Note: which branch you're on, what's staged vs unstaged, and what remotes exist.

Step 2: Check for upstream remote

If the repo is a fork and an upstream remote exists, sync it in Step 5. If there's only origin, skip Step 5 and go straight to Step 6.

rtk git remote -v | grep upstream

Step 3: Branch local changes off main (if needed)

On main with local changes → create a feature branch so the GitHub sync lands cleanly before the rebase:

rtk git checkout -b feature/<short-description>

Name from content (3-5 words, kebab-case).

Already on a feature branch → proceed to commit.

Feature branch already fully committed → skip to Step 5 or 6.

Step 4: Commit

rtk git commit -m "$(cat <<'EOF'
<short imperative summary under 72 chars>

- <group of related changes>
- <group of related changes>
EOF
)"

Do NOT use --no-verify. Fix hook failures instead:

Hook	Symptom	Fix
check-shebang-scripts-are-executable	file has shebang but isn't executable	git add --chmod=+x <file> then retry
trailing-whitespace	hook auto-fixed files	re-stage modified files then retry
py-psscriptanalyzer Format	formatter auto-fixed PS files	re-stage modified files then retry
biome check exits 1 "no files processed"	staged JSON is in biome's ignore list	add --no-errors-on-unmatched to the entry: in .pre-commit-config.yaml, re-stage
ruff lint errors	Python lint violations	uv run ruff check --fix src/ tests/ scripts/ then re-stage
ruff-format	formatting violations	uv run ruff format src/ tests/ scripts/ then re-stage

After each hook auto-fix, re-stage the modified files and retry the commit.

Step 5: Sync main with upstream (forks only)

Skip if no upstream remote — go to Step 6.

rtk git checkout main
rtk git fetch upstream
rtk git pull --autostash upstream main

--autostash saves local uncommitted changes, applies the upstream merge, re-applies them. If re-apply fails: git stash pop and resolve manually.

Conflict rule of thumb: upstream owns auto-generated files; keep local changes for code and config.

After resolving: git add <resolved-files> && git merge --continue

Step 6: Sync main with GitHub (origin)

Picks up any commits on GitHub that aren't local yet:

rtk git checkout main
rtk git pull --rebase --autostash origin main

Step 7: Merge feature branch

Prefer fast-forward for a linear history:

rtk git merge --ff-only feature/<branch-name>

If histories have diverged:

rtk git merge feature/<branch-name>

Resolve conflicts, then git merge --continue.

Step 8: Push to GitHub

rtk git push origin main

If rejected (GitHub has commits local doesn't): go back to Step 6, then retry push.

Step 9: Clean up feature branch

rtk git branch -d feature/<branch-name>
rtk git push origin --delete feature/<branch-name>

Step 10: Commit any remaining workflow changes

Files modified during the workflow itself (e.g. AGENTS.md, config files) won't be on the feature branch. Commit them directly to main:

rtk git add <files>
rtk git commit -m "<short message>"
rtk git push origin main