NICHOLAS J. MATIASZ, Ph.D.

How to contribute to an open-source repository on GitHub

On GitHub, you can submit changes to a public repository with three main steps:

  1. Fork the repository.
  2. Commit your changes.
  3. Submit a pull request.

This post walks you through each step.

Before you start, you need Git installed and an account on GitHub. You should also read the project’s README or CONTRIBUTING files to see if they give any guidelines for submitting pull requests.

Fork the repository

Sign in to GitHub, and go to the repository that you’d like to contribute to. The URL will look like

https://github.com/owners-username/repository-name

In the top-right corner, click “Fork.”

Click "Fork."

GitHub will bring you to your fork. The URL will look like

https://github.com/your-username/repository-name

Clone your fork

To clone your fork, first copy the fork’s URL.

Copy the forked repository's URL to the clipboard.

Then, in your terminal, enter this command, replacing the URL below by pasting the fork’s URL.

$ git clone https://github.com/your-username/repository-name.git

This clone command creates a local copy of the repository on your machine. Before entering any more Git commands, cd into the repository.

$ cd repository-name

Add an upstream remote

You should periodically bring your fork up-to-date by fetching changes that have occurred in the original repository. In this case, the original repository is called the upstream repository. Before you fetch upstream changes in your fork, you’ll need to add the upstream repository as a remote.

Go to the original repository’s page.

https://github.com/owners-username/repository-name

Copy the original repository’s URL.

Copy the original repository's URL to the clipboard.

In your terminal, enter this command, replacing the URL below by pasting the original repository’s URL.

$ git remote add upstream https://github.com/owners-username/repository-name.git

To check if this worked, enter this command.

$ git remote -v

The output should look like this.

origin  https://github.com/your-username/repository-name.git (fetch)
origin  https://github.com/your-username/repository-name.git (push)
upstream  https://github.com/owners-username/repository-name.git (fetch)
upstream  https://github.com/owners-username/repository-name.git (push)

Bring your fork up-to-date

You can now bring your fork up-to-date with changes that occur in the original (upstream) repository.

In your fork, fetch changes from the original repository with this command.

$ git fetch upstream

Check out your master branch.

$ git checkout master

To bring your fork’s master branch up-to-date with the original repository’s, use this command to merge the history of the upstream repository’s master branch into your fork’s master branch.

$ git merge upstream/master

To bring a different branch up-to-date with the upstream repository, simply replace master in the two commands above with the name of the branch you’d like to sync.

Having configured your fork, you’re ready to code.

Commit your changes

While you have your master branch checked out (or whichever branch you synced above), check out a new branch to work on a particular change.

$ git checkout -b readme_update

Do your work, and add your changes to the index. You can add all of the files that you’ve changed or created…

$ git add -A

…or you can add only specific files.

$ git add README.md

Commit your changes on this new branch.

$ git commit -m "Update README file"

If the upstream branch you’re working off of has changed since you checked out your new branch, you have the option to rebase your new branch off of the upstream branch. This step will give you the opportunity to resolve merge conflicts locally before you submit a pull request.

$ git pull --rebase upstream master

If you’re working off of an upstream branch other than master, simply use the upstream branch’s name in place of master above.

Having finished your work, you’re ready to submit these changes to the original (upstream) repository.

Submit a pull request

In your fork, push your branch to your origin remote.

$ git push origin readme_update

Go to the original repository’s page.

https://github.com/owners-username/repository-name

Click “Pull Requests.”

Click "Pull Requests."

Click “New pull request.”

Click "New pull request."

Since you pushed your branch to your fork’s origin remote, you need to click “compare across forks” to select your branch.

Click "compare across forks."

Set the “base fork” to the original (upstream) repository, and set the “base branch” to master (or whichever branch you synced with earlier). Set the “head fork” to your fork, and set the “compare branch” to whichever branch you pushed up earlier (in this example, it’s readme_update).

Set the "base fork" to the original (upstream) repository, and set the "base branch" to `master` (or whichever branch you synced with earlier). Set the "head fork" to your forked repository, and set the "compare branch" to whichever branch you pushed up earlier (in this example, it's `readme_update`).

Click “Create pull request.”

Click "Create pull request."

In the comment box, explain the reason for your pull request, and describe what your code does.

To submit your pull request, click “Create pull request” a final time.

Click "Create pull request."

A shortcut

After pushing up your branch, GitHub may show you an option like the one below—either on the original repository’s page or on your fork’s page.

A shortcut for creating a pull request.

As a shortcut, you can click “Compare & pull request.” Then follow the rest of the steps described above to submit your pull request.

Subscribe to my mailing list if you’d like to read more.