English | 日本語
A GitHub CLI extension that brings every local branch up to date with its remote in one command, and cleans up the branches that were merged and deleted there.
It is an independent reimplementation of hub sync for people who moved from hub to gh.
$ gh sync
Updated branch main (was 3f2a1bc).
Updated branch feature/login (was 9d04e7a).
Deleted branch fix/typo (was c81b2d5, merged via #42).
warning: 'wip/experiment' has 2 commits not in 'origin/wip/experiment'; not updatedgh extension install him0/gh-syncIt needs GitHub CLI 2.0 or later and Git 2.23 or later. Precompiled binaries are published for macOS, Linux, Windows and FreeBSD, so Go is not required.
Upgrade with gh extension upgrade sync, or install a specific version with gh extension install him0/gh-sync --pin v0.5.0.
Run gh sync anywhere inside a git repository.
- Picks the main remote: the one given with
--remote, otherwise the first ofupstream,githubandoriginthat exists, otherwise the first remote. In a fork with anupstreamremote, your branches are synced with the parent repository. - Fetches it with
git fetch --prune, together with every other remote a local branch tracks (such as your fork'sorigin). Branches tracking a remote that can't be fetched are skipped with a warning. - Compares every local branch, except excluded ones, with its upstream, or with the same-named branch on the main remote when it has none.
| Local branch | What gh-sync does |
|---|---|
| Behind | Fast-forwards it |
| Ahead or diverged | Keeps it, with a warning |
| Upstream deleted, and merged | Deletes it |
| Upstream deleted, but not merged | Keeps it, with a warning |
| Up to date, or no counterpart on the remote | Nothing |
A branch whose upstream was deleted counts as merged when either is true:
- All its commits are in the main remote's default branch.
- Its tip is the head, or one of the commits, of a merged pull request. This covers squash and rebase merges, and a branch that is behind its pull request (GitHub's "Update branch", a commit pushed from elsewhere). The message says which one:
Deleted branch <name> (was <sha>, merged via #<number>).
A branch with commits added on top of a merged pull request's head is kept.
Pull requests are looked up with gh api graphql. Only the last 100 commits of each are checked, and nothing extra is fetched. If the lookup fails, the branches that depend on it are kept; see Troubleshooting.
gh is only called for github.com, *.ghe.com, the host in GH_HOST, and hosts you logged in to with gh auth login. A remote on any other host is never sent a token, including one from GH_ENTERPRISE_TOKEN.
- gh-sync never merges, rebases, force-updates or pushes. A branch with local-only commits is always kept.
- Only a branch whose upstream git pruned (
[gone]) can be deleted. Branches that never had an upstream, or whose upstream is outside the fetch refspec (a single-branch clone,refs/pull/<N>/headfromgh pr checkout), are never deleted. - If the branch to delete is checked out, gh-sync first switches to the default branch, creating it from the main remote if needed.
- A branch checked out in another worktree is never updated, and is deleted only with
--remove-worktrees. - Only local branches are updated. After syncing a fork against
upstream, push to update the fork too (e.g.git push origin main).
| Option | Description |
|---|---|
--dry-run |
Print Would update branch ... / Would delete branch ... / Would remove worktree ... without changing any branch or worktree. The fetch still runs |
--verbose |
Also print, to stderr, the git and gh commands that change or look something up, and notes on skipped branches |
--remote=NAME |
Use NAME as the main remote |
--exclude=GLOB |
Leave branches matching GLOB alone. Repeatable. See Excluding branches |
--remove-worktrees |
Remove the worktree of a branch to delete, then delete the branch. Deletes ignored files. See Removing worktrees |
--color=WHEN |
auto (default), always or never |
--version |
Print the version |
--help |
Print usage |
gh-sync takes no positional arguments: gh sync dry-run (missing --) is rejected instead of running a sync.
Excluded branches are never fast-forwarded or deleted. Patterns come from --exclude and from the gh-sync.exclude git config key, and all of them apply:
git config --add gh-sync.exclude 'wip/*' # add --global for every repository
gh sync --exclude='wip/*' --exclude=tmpPatterns are matched against the whole branch name with Go's path.Match, so * does not match /: wip/* matches wip/foo but not wip/foo/bar.
- stdout: branch updates, deletions and switches, and worktree removals.
- stderr: warnings, hints, notes, errors and
--verboseoutput. When it is a terminal, also fetch progress, andAlready up to date.if nothing was updated, deleted, warned about or skipped because of another worktree. - Exit status:
1when gh-sync could not run or an update, deletion or fetch failed. Otherwise0, including when branches were skipped with a warning or a note. - Color: updated branches are green, deleted ones red, warnings yellow and errors bold red. With
--color=auto, stdout and stderr are each colorized only when they are a terminal, and a non-emptyNO_COLORdisables color.
git refuses to move or delete a branch that is checked out in another worktree, so gh-sync skips it and reports the skipped branches together at the end:
warning: 2 merged branches are still checked out in other worktrees; not deleted:
feature/a .claude/worktrees/eager-wiggling-moonbeam
feature/long /home/me/elsewhere/wt
hint: remove a worktree with `git worktree remove <path>`, or run `gh sync --remove-worktrees` to remove the clean ones
note: 3 branches checked out in other worktrees are behind their upstream; not updated- The warning lists the branches that would have been deleted. A worktree inside the main worktree is shown relative to it, any other with its absolute path.
- The note counts the branches that would have been fast-forwarded;
--verboselists them the same way. Update one withgit pull --ff-onlyin its worktree.
With --remove-worktrees, or git config gh-sync.removeWorktrees true, gh-sync removes the worktree of a branch it is about to delete with git worktree remove, never with --force, then deletes the branch:
Removed worktree .claude/worktrees/eager-wiggling-moonbeam.
Deleted branch feature/a (was 1a2b3c4, merged via #12).It is off by default because of what it can't protect:
- Ignored files are deleted without asking. git only refuses for modified or untracked files, so an ignored
.envor build output in the worktree is lost. - gh-sync can't tell whether a shell or an agent session is still running in the worktree. Its working directory disappears.
A worktree git refuses to remove is kept with its branch, and the exit status stays 0:
warning: 'feature/b' is checked out in .claude/worktrees/calm-river, which has modified or untracked files; not deleted
warning: 'feature/c' is checked out in /home/me/elsewhere/wt, which is locked; not deletedAny other refusal, such as a worktree with submodules, is reported as ..., which couldn't be removed: <git's message>; not deleted.
- The flag overrides the config:
--remove-worktrees=falseturns it off for one run. - Worktrees of branches that are only behind are never removed, and neither is the main worktree.
--dry-runprintsWould remove worktree <path>.or the same warnings, fromgit statusand the lock. It can't predict every refusal (submodules, for example).
could not determine default branch
The main remote has no usable HEAD, main or master. Set it with git remote set-head <remote> --auto.
warning: couldn't fast-forward '<name>'
Local changes in the checked-out branch would be overwritten. Commit or stash them and run gh sync again.
warning: '<name>' upstream config is broken; skipping
branch.<name>.merge is missing or invalid. Fix it with git branch --set-upstream-to=<remote>/<branch> <name>.
warning: couldn't look up merged pull requests: <reason>
gh is not authenticated, the remote is not on GitHub, or the API failed or took more than 30 seconds. Branches whose commits are not in the default branch are kept, with ... and pull requests couldn't be looked up; not deleted, until the lookup works. Check gh auth status. For GitHub Enterprise Server, the host must be logged in to with gh auth login --hostname <host> or named by GH_HOST; a token in GH_ENTERPRISE_TOKEN alone is not enough. SSH host aliases from ~/.ssh/config and ssh.github.com are resolved with ssh -G.
When reporting a bug, please include the output of gh sync --version and gh sync --verbose.
Tool versions and tasks are managed with mise.
mise run build # build ./gh-sync
mise run test # go test ./...
mise run lint # go vet + gofmt check + golangci-lintPushing a v* tag publishes a release. See CLAUDE.md for the contribution rules.