git-sync skill
Syncs a feature branch with its base or upstream branch using merge or rebase strategies with automatic stash handling.
- GitHub stars
- 8
- Files
- 3
- Last commit
- Oct 28, 2026
- License
- MIT
- Allowed tools
- —
What does the git-sync skill do?
git-sync syncs a feature branch with its base or upstream branch using merge or rebase strategies with automatic stash handling.
Summary generated from the skill's SKILL.md.
About the git-sync skill
Keeping feature branches up to date with main or develop branches is what git-sync handles for developers working in Git repositories. It automates the process of pulling changes from a base or upstream branch into your current working branch using either a merge or rebase strategy. The tool is designed for ad-hoc branch updates rather than formal release management or hotfix promotions.
When an agent loads this skill, it performs a multi-phase workflow that begins by inspecting the current branch state using git status and git log. It can automatically detect the base branch through GitHub CLI or local git configurations. To prevent data loss, the skill can use the --stash flag to temporarily save uncommitted changes before the sync and pop them once the process completes. It relies on standard git commands and provides specific warnings if a rebase is requested on a branch that has already been pushed to a remote.
Users can customize the operation with arguments like --rebase for history rewriting, --base to specify a target branch, or --upstream to sync from a fork's upstream remote. If conflicts arise during a merge or rebase, the skill identifies the specific files involved and stops to allow for manual resolution.
What an agent can do with it
- 1Update feature branch with mainSynchronize your current working branch with the main branch using the default merge strategy.
- 2Rebase onto a specific branchApply your local commits on top of the latest changes from the develop branch using a rebase.
- 3Sync a fork from upstreamPull the latest changes from the upstream remote into your local fork to keep it current.
- 4Sync while preserving local changesPerform a branch synchronization while automatically stashing your uncommitted work to avoid errors.
Written from the skill's SKILL.md. Every use case is checked against a quote from it.
How to install the git-sync skill
Each command copies the skill folder into the client's skills directory. Restart the client or start a new session to load it.Install the git-sync skill in Plugin
/plugin marketplace add mgiovani/cc-arsenal /plugin install cc-arsenal@cc-arsenal-marketplace
Install the git-sync skill in Claude Code
~/.claude/skills/git-sync/SKILL.md
$ npx degit mgiovani/cc-arsenal/skills/git-sync ~/.claude/skills/git-syncInstall the git-sync skill in Claude Code (project)
.claude/skills/git-sync/SKILL.md
$ npx degit mgiovani/cc-arsenal/skills/git-sync .claude/skills/git-syncInstall the git-sync skill in Codex
~/.agents/skills/git-sync/SKILL.md
$ npx degit mgiovani/cc-arsenal/skills/git-sync ~/.agents/skills/git-syncInstall the git-sync skill in Gemini CLI
~/.gemini/skills/git-sync/SKILL.md
$ npx degit mgiovani/cc-arsenal/skills/git-sync ~/.gemini/skills/git-syncInstall the git-sync skill in Claude.ai
npx degit mgiovani/cc-arsenal/skills/git-sync git-sync && zip -r git-sync.zip git-sync # claude.ai → Customize → Skills → + → Create skill → Upload a skill → git-sync.zip
SKILL.md
View on GitHubGit Sync
Sync the current branch with its base or upstream branch. Defaults to merge to preserve history; rebase is opt-in only. Only ever act on what git status and git log actually show: never guess branch state or conflicts.
Workflow
Phase 1: Detect & Decide
Run the following to understand current branch state:
git branch --show-current
git status --porcelain
git remote -v
git log --oneline HEAD..origin/main 2>/dev/null | head -20
git log --oneline origin/main..HEAD 2>/dev/null | head -20
Also check whether the branch is pushed to remote (git log origin/<branch>..HEAD: an error means local-only).
Determine the base branch once, and reuse the result for the rest of the run:
- User passed
--base <branch>: use it. - Otherwise
gh pr view --json baseRefName -q .baseRefName 2>/dev/null(if an open PR exists). - Otherwise
git config branch.<name>.merge. - Otherwise ask the user which base branch to use.
Determine sync strategy:
Merge (default): use when the branch has been pushed to remote, the user did not pass --rebase, or you are unsure.
Rebase (opt-in): use only when the user explicitly passed --rebase.
Fork sync (--upstream) syncs from the upstream remote instead of origin: git fetch upstream && git merge upstream/<base>.
Display the detected state and proposed strategy before proceeding:
Current branch: feature/my-feature
Base branch: main
Strategy: merge (default)
Commits behind: 5
Commits ahead: 2
Dirty tree: no
Phase 2: Pre-sync Safety
- Dirty working tree: with
--stash, rungit stash push -m "git-sync auto-stash"before syncing. Without--stash, abort and tell the user to commit, stash, or re-run with--stash. - Fetch latest:
git fetch origin(andgit fetch upstreamfor fork sync). - Re-check divergence after fetch so the numbers you report are accurate, not the pre-fetch snapshot.
Phase 3: Execute & Report
Merge: git merge origin/<base>
Rebase, local-only branch: git rebase origin/<base>
Rebase, pushed branch: warn before rewriting shared history:
WARNING: This branch has been pushed to remote.
Rebasing will require a force-push, which rewrites history.
This is ONLY safe if no one else has pulled this branch.
Proceed? [y/N]
If confirmed:
git rebase origin/<base>
git push --force-with-lease origin <branch>
On merge/rebase conflict, do not guess how to resolve them:
git diff --name-only --diff-filter=Uto list conflicting files.- Report the exact file list, e.g.:
Conflicts in 2 files: src/api/client.ts src/api/types.ts Resolve manually, then run `git merge --continue` (or `git rebase --continue`). Or run `git merge --abort` (or `git rebase --abort`) to back out. - Stop and wait. Do not attempt automatic resolution.
After a successful sync:
- If a stash was auto-created in Phase 2, pop it now:
git stash pop. If the pop itself conflicts, report those conflicting files the same way as a merge conflict. - Gather real numbers, don't estimate:
git log --oneline -5 git log --oneline origin/<base>..HEAD | wc -l - Report, using only values from the commands above:
Include whether force-push was used, and mentionSynced feature/my-feature onto main (merge). Now 2 commits ahead of main, 0 behind. Stash popped cleanly.git rerereif conflicts occurred during this run.
Argument Parsing
--rebase: use rebase instead of merge--base <branch>: specify the base branch (default: auto-detect)--upstream: sync fromupstreamremote instead oforigin(fork workflow)--stash: auto-stash dirty changes before sync, pop after
Important Notes
- Never force push to main/master, regardless of flags or user insistence.
- Merge is the safe default for shared branches; only rebase branches you're sure are local-only or where the user explicitly accepted the force-push warning.
- Use
--force-with-lease, never bare--force, so a rebase-push can't clobber someone else's commits. - Fork workflow requires the
upstreamremote to already be configured (git remote add upstream <url>).
Examples
# Sync with main using merge (default)
/git-sync
# Sync with develop branch
/git-sync --base develop
# Rebase onto main (will warn if branch is already pushed)
/git-sync --rebase
# Sync, stashing local changes first
/git-sync --stash
# Fork sync: pull upstream changes into your fork
/git-sync --upstream --base main
Files in this skill
3git-sync skill questions
How do I install the git-sync skill in Claude Code?
Run npx degit mgiovani/cc-arsenal/skills/git-sync ~/.claude/skills/git-sync. Claude Code loads skills from ~/.claude/skills (all projects) or .claude/skills (one project) and uses a skill when its description matches the task.
Which clients can use the git-sync skill?
Any client that reads the Agent Skills format: Claude Code, Codex, Gemini CLI and claude.ai (upload as a ZIP). Scripts in the skill run only where the client allows code execution.
How do I sync my branch with a specific base branch?
You can specify the base branch using the --base flag, for example: /git-sync --base develop.
Can I use this tool to sync my fork with the original repository?
Yes, use the --upstream flag to sync from the upstream remote instead of origin.
What happens if I have uncommitted changes in my working directory?
If you use the --stash flag, the tool will automatically stash your changes before syncing and pop them afterward.