Git Forked Repository Operations

External

• https://docs.github.com/en/pull-requests/collaborating-with-pull-requests/working-with-forks/syncing-a-fork

Internal

• Git Operations

TODO

Merge with: https://kb.novaordis.com/index.php/GitHub_Procedures#Make_a_Pull_Request_from_a_Forked_Repository

Overview

For terminology, see upstream/base and head repositories.

The typical GitHub forked repository topology is similar to:

Initial Setup

Fork

Go to GitHub UI and click on the "Fork" button at the top of the page. Use your own "personal" organization ("ovidiu") to fork into.

Clone

Clone as usual:

git clone git@github.com:ovidiu/blue.git

Establish Relationships

Setup the "upstream" Repository

Establish a direct relationship between the local clone and the "upstream" repository. This will allow to pull the latest version of branches directly from the upstream repository.

git remote add upstream git@github.com:blue/blue.git

.git/config will contain:

[remote "upstream"]
      url = git@github.com:blue/blue.git
      fetch = +refs/heads/*:refs/remotes/upstream/*

This will allow us to fetch directly from "upstream"

git fetch upstream

Configure the "main" Branch to Update From Upstream

git fetch upstream
git branch --set-upstream-to=upstream/main main

This will configure the local "main" branch to track upstream's "main" branch. The .git/config will look like:

[branch "main"]
     remote = upstream
     merge = refs/heads/main

git pull will automatically apply upstream's "main" branch changes to the local main.

To fetch PRs, you can optionally add:

  fetch = +refs/pull/*/head:refs/remotes/upstream/pr/*

PR Cycle

Send a PR

Push the commit in the head repository.

PR will show up both in the origin and upstream repository UI.

From the Origin Repository UI

Click "Compare & pull request"

The UI will give you the default choice to send the PR against the base repository while "Create pull request". Use it.

From the Upstream Repository UI

TODO

Merge the PR

Upon approval, merge the PR in upstream. The branch in the head repository will remain, and it has to be deleted explicitly as described in Clean Up the Branch section below.

Sync the Repositories after the PR Merge

There are two repositories to be synced: the origin repository and its local clone.

The local clone can be just simply git pull because its main branch is tracking the upstream repository.

The origin repository's main branch can be synced from the GitHub UI: In the origin repository's UI, use "Fetch upstream" button, then "Fetch and Merge".

CLI

Assuming the local repository was set as shown above, git pull will bring the latest "main" changes and will allow us to delete the local feature branch after it was merged in upstream.

git pull

To clean up branches:

git remote prune origin
git remote prune upstream

How to deal with the leftover branch in the origin repository?

How to deal with the origin and upstream growing out of sync?