When you're contributing to a project, you typically don't edit the project directly. You create a copy of the project's repository, or repo, for yourself and make all of your changes there before submitting them to the project. This copy is called a fork.

To begin, you must be signed into your GitHub account. Then use a browser to navigate to the repo for the project to which you plan to contribute. I'm going to be contributing to the Adafruit Circuit Playground Express library.

The first thing you want to do is fork the repo. Click the Fork button on the right side of the page to fork a copy of the repo to your account.

circuitpython_GitHubForkForkingInProgress.png
Forking!

Great job! You now have your very own GitHub copy of the project repo to which you're going to contribute. You're ready for the next step!

Clone Your Repo

The next thing you'll need to do is download a copy of your new repo on your computer so you can start working on it. This is called creating a clone or cloning. Create a directory on your computer to hold your projects. Mine is in my home folder and is called repos.

On the page for your repo, you'll find a green Code button.

Click it to find the clone URL for your new fork. The URL will look something like this:

https://github.com/kattni/Adafruit_CircuitPython_CircuitPlayground.git

Click the Copy button to copy the URL to your clipboard.

Open your terminal program and navigate to your new directory using the cd command.

When you clone a repo, Git assigns the repo on GitHub an alias, which by default is "origin". You may in the future have a reason to clone a repo that is not your own fork, and it can be confusing when all repos are called origin. So, for my repos, I like to set the alias to the repo owner's GitHub user ID. In the case of my fork, this is my GitHub user ID. This makes it easier to remember when I'm contributing to my own repos versus contributing to someone else's repo.

Once you're in your new directory, enter the clone command. Replace youruserid with your GitHub user ID, and paste the URL from your clipboard:

git clone -o youruserid https://your-fork-URL

This will create a local copy of the repository on your computer in a directory with the same name as the repo. So, now I have a new directory, ~/repos/Adafruit_CircuitPython_CircuitPlayground, which contains a copy of the newly forked repo.

Now, use the cd command to move into that directory.

When changes are merged with the project, they're merged into the original repo. This includes your final changes and changes submitted by others.

Changes made to the original repo do not automatically update to your repo. You have to manually fetch those changes and merge them into your own repo. To do this, you need to add what is called a remote. A remote allows you to fetch the changes from the original project to stay updated.

Use your browser to navigate to the page for the original repo. Click the Code button, then click the copy button to copy the URL for the original repo to your clipboard. Remember to use SSH if you setup GitHub to use it.

When you create a copy of a project, the original project is considered to be upstream. Since you're getting the updates from upstream, often the remote is called upstream. However, in exactly the same way we called your remote your GitHub ID, it's easier to call the original remote by the owner's GitHub ID. The original repo here is owned by Adafruit, so I'm going to name the remote adafruit.

While in the directory for your newly cloned repo, enter the following remote command, changing ownerID to the original project owner's GitHub ID, and pasting the URL from the clipboard:

git remote add ownerID https://original-project-url

Your local repo is set up and ready to go. You forked the repo, cloned a local copy, and prepared to keep it updated.

Now you're ready to begin working with it!

This guide was first published on Jun 29, 2018. It was last updated on Jun 29, 2018.
This page (Grab Your Fork) was last updated on Oct 24, 2020.