Sync a GitHub Fork Safely with gh repo sync

You will finish with a repeatable way to update a GitHub fork or another destination repository from a source repository, while knowing exactly which branch is affected and when a hard reset is being requested. The examples use GitHub CLI 2.87.3, installed here on 23 September 2026.

Allow about ten minutes for a routine sync, plus time to inspect the branch if it has diverged. You need the gh command, an authenticated GitHub account with permission to update the destination, and a source repository whose branch you are allowed to read. Nothing in this guide needs sudo. The sync changes repository state on GitHub, so treat the final command as an operational change rather than a harmless status check.

1. Check the installed command

Start with read-only checks. This confirms the version and keeps the option names tied to the binary you are about to use:

$ gh --version
gh version 2.87.3 (2026-02-23)
https://github.com/cli/cli/releases/tag/v2.87.3
$ gh repo sync --help

The command has this shape:

gh repo sync [<destination-repository>] [flags]

The destination is optional. With no argument, gh uses the repository associated with the current local directory. With an argument such as OWNER/REPO, it updates that remote repository instead.

2. Establish the source, destination and branch

By default, the source is the destination repository's parent. This is the usual fork workflow: the fork is the destination and its upstream repository is the source. You can select another source with --source or -s.

The branch defaults to the default branch. Do not silently assume that means main or master. If the branch matters, name it explicitly with --branch or -b:

$ gh repo sync example/project-fork --branch main

For a source that is not the fork parent, specify both repositories:

$ gh repo sync example/project-fork \
    --source example/project-upstream \
    --branch main

These commands are included to show the syntax only. They will contact GitHub and, if accepted, update the destination branch. Replace every owner, repository and branch with values you have checked.

Before changing anything, inspect the repositories in the GitHub web interface or with an existing read-only review process. Confirm that the destination is the repository you mean, that the source is authoritative for this operation, and that the branch names match. A typo in an owner or repository name is not a safe way to discover what a command does.

3. Perform an ordinary fast-forward sync

Once the values are confirmed, sync a fork from its parent without --force:

$ gh repo sync example/project-fork --branch main

Without --force, gh repo sync uses a fast-forward update. In practical terms, it asks GitHub to move the destination branch forward so it matches the source branch without replacing the destination's existing history. If the branches have diverged, the ordinary sync cannot make them equal by fast-forwarding. Stop and inspect the divergence rather than adding a flag by habit.

A successful command may produce little or no output. Check its status immediately:

$ gh repo sync example/project-fork --branch main
$ printf 'sync exit status: %s\n' "$?"
sync exit status: 0

Exit status zero confirms that this invocation completed successfully. It does not tell you that you selected the right repositories, so the pre-flight review still matters. For an independent check, compare the branch commit IDs through your normal GitHub review or API tooling and confirm that the source and destination now point at the same commit.

4. Treat --force as a history-changing operation

The --force flag changes the update method. It hard-resets the destination branch to match the source branch:

$ gh repo sync example/project-fork --branch main --force

That can discard commits that exist on the destination branch but not on the source. It may also disrupt people or automation using the destination branch. Do not use it merely to clear an error. First record the destination tip, review the commits that would disappear, and agree a maintenance window if the branch is shared.

For a fork, the ordinary recovery is to make a backup reference before the forced sync using a process your team already trusts. For example, create a backup branch in the GitHub interface or push a clearly named backup branch with Git, then verify that the backup commit is visible. If the forced operation has already happened and the old commit was not backed up, stop making further changes and use the repository's reflog, pull requests or hosting recovery facilities while the old commit is still reachable. gh repo sync has no undo option.

5. Diagnose the common failures

A non-zero result does not mean that --force is the answer. Check the most likely boundary first:

• A missing or misspelled repository usually means the destination or source value is wrong.
• An authentication or permission error means the current gh account cannot perform the requested operation. Re-authenticate only through your normal controlled process; do not paste a token into shell history.
• A branch error means the named branch is absent or the source and destination do not expose the branch you selected. Verify the spelling and repository contents.
• A divergence error means the destination has history that cannot be advanced by the ordinary update. Review that history before deciding whether to merge, rebase, preserve it, or deliberately replace it.

Keep diagnostics separate from the change. You can rerun the help command at any time:

$ gh repo sync --help

Do not run the sync repeatedly while investigating. Repetition will not make an incorrect source safe, and repeated forced operations can make recovery harder.