Maintaining Forks#

Setting Remote Sources in git#

When cloning a repository git will automatically set the source URL as a remote source with the default name of origin. To list the remote sources currently configured for a clone, run git remote -v. For example, cloning the repository containing these working practices via ssh will produce the output,

git remote -v

# origin    git@github.com:MetOffice/simulation-systems.git (fetch)
# origin    git@github.com:MetOffice/simulation-systems.git (push)

It is possible to set another repository as a remote source using the syntax,

git remote add <name> <url>

The URL for the desired repository can be found from the Code button on GitHub (see Cloning a Repository).

Tip

Cloning a repository with the gh cli will automatically set the upstream repository as remote named upstream.

A common use case for this would be to add the upstream repository as a remote source in order to merge the main branch into your development branch. For example, in a clone of a fork of these working practices,

git remote add upstream git@github.com:MetOffice/simulation-systems.git
git remote -v

# origin    git@github.com:userName/simulation-systems.git (fetch)
# origin    git@github.com:userName/simulation-systems.git (push)
# upstream  git@github.com:MetOffice/simulation-systems.git (fetch)
# upstream  git@github.com:MetOffice/simulation-systems.git (push)

You will need to manually sync the fork with the remote source by fetching it with the command git fetch <name>, eg.

git fetch upstream

To interact with remote branches you can use the <name>/<branch> syntax. For example, to merge the upstream main into the current branch, use,

git merge upstream/main

Syncing a Fork#

Most work to maintain a fork involves syncing it with the upstream repository. Syncing a fork will ensure that changes to the upstream repository are copied into the fork. Syncing is done on a per branch basis. For example, after a new release, syncing the stable branch will ensure the forks stable branch contains the newly released code.

Important

It is recommended that developers do not modify the synced branches from upstream in their forks as this may cause issues with merge conflicts when syncing a fork. Instead all work should be carried out in a branch.

Navigate to your fork in GitHub that you wish to sync. Select the Sync Fork button and if required, update the branch. This will only sync the branch you are currently on - to sync other branches select one from the branch dropdown menu. You may want to sync both stable and main, particularly at a release.

../_images/sync_fork_light.png ../_images/sync_fork_dark.png

The synced branch will still only exist in the remote repository. If you require them in a local clone make sure to fetch or pull the repository.

gh repo sync [<owner>/<repo>] [-b <branch>]

  • The command syncs changes from a remote repository to your fork or local copy.

  • Both <owner>/<repo> and -b <branch> are optional.

  • If -b <branch> isn’t specified, it will sync the default branch (main),

  • There is no built-in gh repo sync option for all branches, therefore the user needs to specify a branch name when not syncing the not the default branch.

  • If you run this without <owner>/<repo>, it will sync changes from the remote origin to your local clone.

    • Doing this will not update your remote fork, this will also require a git push command.

  • By providing your username and fork name to <owner>/<repo>, it will sync changes from the upstream parent repository into your remote fork.

    • Doing this will not update your local clone, this will also require a git pull command for each branch you wish to update.

Ensure that the upstream repository is available as a remote source and the latest changes have been fetched. See setting git remote sources for more details.

Then run the following commands for each branch you wish to sync. The example below will use main.

# Change to the desired branch
git switch main

# Merge in changes from the upstream
git merge upstream/main

# Push the changes back to the remote fork
git push

Tip

Note that the options above will result in the synced branch being available in different locations. Using the web browser will not update your local clone while using git commands will not update the remote repository without pushing. gh can be used to update either.

Updating Branches#

It will often be necessary to merge in changes from a remote repository into your local branch, eg. when updating your branch to a new release, or when merging in main to resolve conflicts. This can be done by,

Tip

This is only applicable when updating a branch with main in an open PR. For other uses, such as updating an old branch to a new release, see the next tabs.

Navigate to the pull request page and locate the branch status box. This is towards the bottom of the conversation. Here, you can select the button to update the branch. If merge conflicts exist, it will take you to a page where these can be fixed.

../_images/update_branch_light.png ../_images/update_branch_dark.png

Tip

This section gets the changes via your remote fork. You will first update your fork with changes from the upstream repository, then merge the updated main or stable to your development branch. This results in changes to the fork main or stable and so is generally recommended. However, sometimes you may want to skip this, so the next tab would has been provided as an alternative.

Navigate to your clone and ensure that the branch you wish to update is your active branch,

cd /path/to/clone
git switch <desired-branch>

Ensure that your fork is up to date with the upstream repository. See syncing your fork for details on how to do this.

Then ensure that knowledge of any synced changes is available in your local clone,

git fetch origin

Now you can merge the synced branch into your development branch,

git merge origin/<branch>

If there are any merge conflicts you can now fix these using your conflict tool of choice.

Tip

This section gets the changes from the upstream repository, and merges these directly onto your branch. It will not update main or stable in your fork.

Navigate to your clone and ensure that the branch you wish to update is your active branch,

cd /path/to/clone
git switch <desired-branch>

Ensure that the upstream repository is available as a remote source. See setting git remote sources for more details.

Then fetch the upstream repository and merge in the desired branch,

git fetch upstream
git merge upstream/<branch>

If there are any merge conflicts you can now fix these using your conflict tool of choice.