git-sync

git-sync

Sync the local default branch and fork/<branch> to upstream/<branch>. The default mode is fast-forward only, so divergent local commits are preserved (the script exits with an error and the user decides what to do). Pass --force to hard-reset and force-push when the user explicitly wants to discard divergent work.

When to use this skill

Use this skill when the user asks to:

• "Sync my fork", "update my fork", "pull upstream into my fork".
• "Bring main up to date with upstream", "fast-forward main".
• "Reset my fork to upstream" (use --force).

Do not use this skill when:

• The repo doesn't have upstream / fork remotes — set them up first with the agitentic:git-fork skill.
• The user wants to merge a feature branch from upstream into a working branch — that's a regular git fetch + git merge, not a sync.

How to invoke

Run the bundled script from inside the repository:

scripts/git-sync [--branch <branch>] [--force]

• --branch <branch> — branch to sync. Defaults to upstream's default branch (read from refs/remotes/upstream/HEAD, usually main).
• --force — allow non-fast-forward updates. Hard-resets local <branch> to upstream/<branch> and force-pushes (--force-with-lease) to fork. Use this when the user explicitly says "reset", "overwrite", or "discard local commits".

The script:

1. Refuses to run if the working tree has uncommitted changes.
2. Verifies upstream and fork remotes exist.
3. Fetches upstream/<branch>.
4. Updates the local <branch> ref:
   • No-op if already at upstream.
   • Fast-forward if local is an ancestor of upstream.
   • Hard-reset if --force is set.
   • Otherwise errors out (divergent commits would be lost).
5. Pushes <branch> to fork. With --force, uses --force-with-lease (refuses to clobber commits the local view doesn't know about).

Examples

User: "Sync my fork with upstream"

scripts/git-sync

User: "Reset main to whatever upstream has"

scripts/git-sync --force

User: "Sync the release-1.x branch"

scripts/git-sync --branch release-1.x

After the script returns, confirm by showing the user git log --oneline -3 main and git rev-parse main fork/main upstream/main.

Requirements

• git
• upstream and fork remotes configured. The agitentic:git-fork skill sets these up.
• For pushing to fork, the user must have push access to the fork repo (typically true if it's their own).