Learn Git Fork & Pull Request Workflow

February 25, 2019

Learn Git Fork & Pull Request Workflow

Whether you are working with open-source or private repositories, you will want to learn the Git fork and pull request workflow. The biggest difference between a Git fork and pull request workflow and a Git branch workflow is that in forking you are working on your own copy of the project and not within the project. You push changes to your fork without changing the original project and then propose changes to the original project via pull requests.

This is the final tutorial in a series. If you’re just joining us, you may want to:

Learn Git Fork & Pull Request Workflow: Real World Example

This blog is built with GatsbyJS, which is a fantastic React-based static site generator, but still very much in development. By default, GatsbyJS generates an excerpt from the first x number of characters in your post, which is not always ideal:

Slack without Open Graph

A feature I wanted was the ability to add custom meta descriptions for SEO and Open Graph:

Slack with Open Graph

This tutorial will walk you through the steps I took to implement this functionality in my blog and open a pull request on the GatsbyJS repository. You can view the PR at https://github.com/gatsbyjs/gatsby/pull/11936

Fork the Repository

Fork a Repository

Navigate to the repository you want to fork. If this is your first fork, congrats! Hit the Fork button in the upper right. You will be treated to a delightful animation and redirected back to your account. Note that now the repository is prepended with your username, with a link pointing to the source of the fork just below it.

Clone a Forked Repository

Now clone your fork.

git clone git@github.com:<your-user-name>/gatsby

Add Upstream

When working with a forked repository, you will want and need to pull changes from the original repo to keep your fork up-to-date. If the original repository is “the source”, then, to use a water-based analogy, we could say that it is “upstream”, which is what we’ll do:

git remote add upstream git@github.com:gatsbyjs/gatsby.git

When you work on the project in the future, simply checkout master and fetch and merge upstream.

git checkout master
git fetch upstream
git merge upstream/master

Get to Work: Checkout a Branch

When working on a fork to which you intend to create pull requests, you will want to keep the master branch up-to-date and separate from the work you are doing in order to mirror the upstream and minimize conflicts. In this example, I created a branch meta-description as that was the feature I was implementing:

git checkout -b meta-description

Work on your feature or bug fix, then add, commit and push to your remote origin.

git push origin meta-description

When submitting a pull request, you won’t push directly to the upstream. Instead, you will push your branch to your remote fork and from there open a PR.

Opening a Pull Request

After pushing your branch to your remote origin, navigate back to your fork of the repository on GitHub. You should be presented with a notification reporting the title of your recently pushed branch and a GitHub green button to Compare & pull request.

Clone a Forked Repository

Click that button and you will be routed to a new page on the upstream repository with a form to enter a title and a description for your pull request. Note that your commit message will be auto-populated in the title field, but you can change it.

Submitting a Pull Request

Also note the diff below the form to review your file changes before submitting your PR, which I recommend you do to ensure no errata found its way into your commit.

Write a descriptive title and a brief, articulate explanation of the pull request.

Click Create Pull Request and your pull request will be added to the queue. You can always return to your PR to edit its title and description. And, if after submitting, you need to make an edit to the PR, just add, commit and push the changes to your fork origin and they will automatically be updated in the upstream.


Jared Nielsen

When we force code to act out of the ordinary… that’s where the magic happens. That’s when we make art. @jarednielsen