Forking

In many environments you can’t just push a feature branch to the official upstream. This is to ensure reliability, cohesion, and security of the official branch.

It is common and customary to fork the upstream to your personal namespace, work on it, and then create a pull request based on that. We explain how this looks in real life.

Create a Fork

There are several ways to create a fork, all of them easy enough:

Forking with GUI

The easiest way to create a fork is to hit the Fork icon in the GitService GUI:

  • Go to the main page of the repo: https://github.com/acme/widgets

  • Hit the Fork button

  • Use your namespace (default) and the original name for the repo

  • Clone your fork to your local system:

    # Your namespace is *tweetie*
git clone https://github.com/tweetie/widgets

  • Add the remote to your fork:

    git remote add upstream https://github.com/acme/widgets

Forking with Github GH

Use the Github gh command to create a fork and the upstream in one blow:

gh repo fork acme/widgets --remote --clone

Forking with Gitlab GLAB

Gitlab’s glab tool is similar:

glab repo fork acme/widgets --remote --clone

Pull Requests via Fork

Once changes are made to the fork, its time to create a pull request (PR). First get ready:

  • Make your changes

  • Push changes up to your forked branch in GitService as usual

GUI

  • Push changes to a branch in your fork

  • Go to your fork on your GitService, switch to the branch to be the PR

  • Click Compare & pull request” => “Create pull request”

  • Make sure the base branch is the official one, and not yours

Using GH and GLAB

Using the Github gh command:

gh pr create

Using the Gitlab glab tool:

glab mr create

These tools will usually prompt you for metadata like:

  • title

  • body

  • base

  • head

  • repo

Normally you just accept the default values and submit.

Rebasing with Forks

Its common when working a fix or feature that your fork becomes out of sync with the original main (or master) branch. This will result in your PR being blocked from merging. To re-synchronize your fork you can do this:

# First sync main as above
git checkout main
git fetch upstream
git rebase upstream; git push --force-with-lease

If your fork is a feature branch, say feature/area51 you additionally do this:

# now sync your feature area51 branch
git checkout feature/area51
git rebase main
git push --force-with-lease

Of course you can bypass synchronization of your main branch and just sync your feature, but that can lead to git insanity.

References