Forks & Open Source

Pull requests inside your own team are simple, because everyone can push branches to the same repository. But you cannot push to a project you do not own, such as a popular open source library or your friend's college project. A fork solves this: it is your own copy of someone else's repository on GitHub, where you can push freely, and from which you can send pull requests back to the original.

This is the workflow behind nearly all open source contributions. In this lesson Rohan, a student in Kochi, contributes a small fix to Priya's sweet-shop repository through a fork.

Fork, origin and upstream

Three copies of the repository are involved, and it helps to name them clearly:

Changes flow in a circle: you push to your fork (origin), open a pull request from the fork to the original, and fetch new work from the original (upstream) to stay up to date.

Step 1: fork and clone

On the original repository page, Rohan clicks Fork, keeps the default name, and clicks Create fork. A copy appears at github.com/rohan-verma/sweet-shop. He clones his fork, not the original, because that is where he can push:

git clone git@github.com:rohan-verma/sweet-shop.git
cd sweet-shop

Step 2: add the upstream remote

The clone knows only about origin (his fork). To receive new work from the original project, he adds a second remote, by convention called upstream:

git remote add upstream https://github.com/priya-sharma/sweet-shop.git
git remote -v

origin	git@github.com:rohan-verma/sweet-shop.git (fetch)
origin	git@github.com:rohan-verma/sweet-shop.git (push)
upstream	https://github.com/priya-sharma/sweet-shop.git (fetch)
upstream	https://github.com/priya-sharma/sweet-shop.git (push)

Using the HTTPS address for upstream is a common trick: he only ever fetches from it, so no login is needed.

Step 3: branch, commit and push to the fork

Never work on the fork's main. Rohan fixes the capitalisation of a heading on a branch and pushes it to his fork:

git switch -c fix-typo-about
git commit -am "Fix capitalisation on about page"
git push -u origin fix-typo-about

Switched to a new branch 'fix-typo-about'
[fix-typo-about bb2cb23] Fix capitalisation on about page
 1 file changed, 1 insertion(+), 1 deletion(-)
To github.com:rohan-verma/sweet-shop.git
 * [new branch]      fix-typo-about -> fix-typo-about
branch 'fix-typo-about' set up to track 'origin/fix-typo-about'.

Step 4: open the pull request

On his fork's page, GitHub shows a Compare & pull request button. The PR form shows four boxes: the base repository (priya-sharma/sweet-shop) and base branch (main) on the left, and the head repository (rohan-verma/sweet-shop) and compare branch (fix-typo-about) on the right. Check that the base repository is the original, write a clear title and description, and create the PR. Maintainers of the original project review it exactly as in Pull Requests & Code Review. By default, GitHub also lets maintainers push small fixes to your PR branch, which speeds things up.

Step 5: keep up with upstream

While Rohan waits for a review, Kabir's "Mention Sunday opening" commit lands in the original main. Rohan's branch is now behind. He fetches from upstream, rebases his branch on top, and updates his PR with a safe force push (the branch belongs only to him):

git fetch upstream
git rebase upstream/main
git push --force-with-lease

From https://github.com/priya-sharma/sweet-shop
 * [new branch]      main       -> upstream/main
Successfully rebased and updated refs/heads/fix-typo-about.
To github.com:rohan-verma/sweet-shop.git
 + bb2cb23...6d7176a fix-typo-about -> fix-typo-about (forced update)

His fork's main is out of date too. He brings it level with the original and pushes it to the fork:

git switch main
git merge --ff-only upstream/main
git push

Switched to branch 'main'
Your branch is up to date with 'origin/main'.
Updating ebe02fd..9f372d2
Fast-forward
 contact.html | 1 +
To github.com:rohan-verma/sweet-shop.git
   ebe02fd..9f372d2  main -> main

--ff-only guarantees he never creates an accidental merge commit on his fork's main. GitHub also has a Sync fork button on the fork's page that updates the fork's main in the browser; then a git pull brings it to the laptop.

Before you contribute to a real project

Open source projects are run by people, often volunteers. A little preparation makes your PR far more likely to be accepted:

• Read CONTRIBUTING.md. It explains how the project wants contributions: coding style, how to run the tests, commit message format, and whether to open an issue first.
• Read the LICENSE. Your contribution is shared under the project's license (MIT, Apache 2.0, GPL and so on).
• Follow the CODE_OF_CONDUCT.md. Be polite and patient in every comment.
• Start small. Look for issues labelled good first issue or help wanted, documentation fixes or missing tests. Comment on the issue to say you are working on it.
• Sign off if asked. Some projects, including the Linux kernel, require a Signed-off-by: line confirming you have the right to submit the code (the Developer Certificate of Origin). git commit -s adds it using your configured name and email.
• Keep the PR focused. One fix per PR, with no unrelated formatting changes.

Common mistakes

• Cloning the original instead of your fork. Your push is then refused. Change the remote: git remote set-url origin git@github.com:you/project.git.
• Working on your fork's main. Your PR then mixes with every future change. Always branch.
• Letting the fork fall far behind. Fetch upstream regularly and rebase your branch before asking for review.
• Opening a large PR without discussion. For anything big, open an issue first and agree on the approach with the maintainers.

Key points

• A fork is your own copy of someone else's repository on GitHub, where you can push.
• Clone your fork (origin) and add the original as upstream.
• Work on a branch, push it to your fork, and open a PR whose base repository is the original.
• Stay in sync with git fetch upstream, rebase your branch, and fast-forward your fork's main (or use Sync fork).
• Read CONTRIBUTING.md, start with good first issue, keep PRs small, and be polite.

git clone git@github.com:you/class-notes.git
cd class-notes
git remote add upstream https://github.com/classmate/class-notes.git
git switch -c fix-date-format
git commit -am "Use DD-MM-YYYY dates in notes"
git push -u origin fix-date-format
git fetch upstream
git rebase upstream/main
git push --force-with-lease
git switch main
git merge --ff-only upstream/main
git push