IntermediateLesson 15 of 307 min read

Forks: Contributing to Someone Else’s Project

Understand upstream, fork and clone, keep your copy in sync with the original, and prepare a tidy pull request from a fork.

In this lesson you will

  • Explain upstream, fork and local clone
  • Add an upstream remote and fetch from it
  • Sync your fork with the original
  • Prepare a pull request from a fork

About 30 minutes

A project that is not yours

Asha spots a small gap in Dev’s project: Tuesday has no backup volunteer. She would like to fix it, but she is not a member of the project and cannot push to it. This is the normal situation for most open projects, and the answer is the fork: your own copy of the whole repository, kept under your own account, where you are free to make any changes you like. When you are ready, you ask the owners to take your change through a pull request.

The picture

Three copies are involved, and keeping them straight is the whole skill. The upstream repository is the original, owned by the maintainer. Your fork is your copy of it on the hosting site, which you can write to. Your local clone is the copy on your own computer. Your clone usually has two remotes: origin, which is your fork, and upstream, which you add yourself so that you can fetch the original’s news.

On GitHub, you make a fork with a button on the project page, and the site creates your copy in a moment. The sessions below imitate it with plain Git: a bare repository stands in for the original, and a bare clone of it stands in for the fork. GitHub cannot be reached from here, so the button is a described step. Everything after it is real Git.

$ mkdir maintainer
$ cd maintainer
$ git init
Initialized empty Git repository in /home/nia/maintainer/.git/
$ printf "Beans: row 1\n" > plan.txt
$ printf "Mon: Nia\nTue: Dev\n" > rota.txt
$ git add .
$ git commit -m "Add plan and rota"
[main (root-commit) 7fbe90f] Add plan and rota
 2 files changed, 3 insertions(+)
 create mode 100644 plan.txt
 create mode 100644 rota.txt
$ cd ..
$ git init --bare upstream.git
Initialized empty Git repository in /home/nia/upstream.git/
$ cd maintainer
$ git remote add origin ../upstream.git
$ git push -u origin main
To ../upstream.git
 * [new branch]      main -> main
branch 'main' set up to track 'origin/main'.
$ cd ..
$ git clone --bare upstream.git fork.git
Cloning into bare repository 'fork.git'...
done.
$ git clone fork.git my-copy
Cloning into 'my-copy'...
done.
$ cd my-copy
$ git config user.name "Asha Rao"
$ git config user.email "asha@example.com"
$ git remote add upstream ../upstream.git
$ git remote -v
origin	/home/nia/fork.git (fetch)
origin	/home/nia/fork.git (push)
upstream	../upstream.git (fetch)
upstream	../upstream.git (push)
$ git switch -c fix-tuesday
Switched to a new branch 'fix-tuesday'
$ sed -i 's/Tue: Dev/Tue: Dev or Asha/' rota.txt
$ git commit -am "Add a Tuesday backup"
[fix-tuesday d08fd22] Add a Tuesday backup
 1 file changed, 1 insertion(+), 1 deletion(-)
$ git push -u origin fix-tuesday
To /home/nia/fork.git
 * [new branch]      fix-tuesday -> fix-tuesday
branch 'fix-tuesday' set up to track 'origin/fix-tuesday'.

Read the output of git remote -v. It shows both addresses: origin is the fork and upstream is the original. Then Asha makes a branch named for her change and pushes it to her fork, not to the original. She never needed permission, because the fork is hers. Making a branch per change, rather than committing on main, keeps her fork’s main clean as a mirror of the original.

The original moves on

While Asha works, the maintainer adds peas to the plan and pushes. Now the original has a commit that Asha does not have. This always happens in a busy project, and it is not a problem. She fetches the original’s news with git fetch upstream, which downloads without changing her files, then compares.

$ cd ../maintainer
$ echo "Peas: row 3" >> plan.txt
$ git commit -am "Add peas"
[main 6a47b77] Add peas
 1 file changed, 1 insertion(+)
$ git push
To ../upstream.git
   7fbe90f..6a47b77  main -> main
$ cd ../my-copy
$ git fetch upstream
From ../upstream
 * [new branch]      main       -> upstream/main
$ git rev-list --left-right --count upstream/main...fix-tuesday
1	1
$ git log --oneline --graph --all
* 6a47b77 Add peas
| * d08fd22 Add a Tuesday backup
|/
* 7fbe90f Add plan and rota

The counting command printed two numbers, 1 and 1: the original is 1 commit ahead of her branch, and her branch holds 1 commit that the original lacks. The graph shows the two lines splitting from the shared first commit. This is the same shape as in lesson 8, and the same tools fix it.

Syncing the fork

The method has four steps. Fetch from upstream. Switch to your main and merge upstream/main into it. Push your main to your fork. Then bring the new work into your change branch, so that it sits on top of the latest original. On GitHub there is also a button on the fork’s page that does the sync step for you. Many people prefer the command line because it works the same way everywhere.

$ git switch main
Switched to branch 'main'
Your branch is up to date with 'origin/main'.
$ git merge upstream/main
Updating 7fbe90f..6a47b77
Fast-forward
 plan.txt | 1 +
 1 file changed, 1 insertion(+)
$ git push origin main
To /home/nia/fork.git
   7fbe90f..6a47b77  main -> main
$ git switch fix-tuesday
Switched to branch 'fix-tuesday'
Your branch is up to date with 'origin/fix-tuesday'.
$ git merge main --no-edit
Merge made by the 'ort' strategy.
 plan.txt | 1 +
 1 file changed, 1 insertion(+)
$ git push
To /home/nia/fork.git
   d08fd22..4fd7d7c  fix-tuesday -> fix-tuesday
$ git log --oneline --graph
*   4fd7d7c Merge branch 'main' into fix-tuesday
|\
| * 6a47b77 Add peas
* | d08fd22 Add a Tuesday backup
|/
* 7fbe90f Add plan and rota

Now her fork’s main matches the original, and her change branch contains the original’s newest commit as well as her own. A pull request from this branch will be easy for the maintainer to merge, because nothing is out of date.

Opening the pull request

The final step is on the website. From her fork, Asha opens a pull request whose base is the original’s main and whose head is her change branch. She writes a title, a short description, and a closing word if an issue exists. This is a pattern, not something run here, and the page wording changes over time. After that, the maintainer reviews it as in lesson 14, and may ask for changes. She makes them on the same branch and pushes again, and the pull request updates itself.

Good manners for contributors

  • Read the project’s contributing notes before you start.
  • Look for an issue first. For anything big, ask before you spend a week on it.
  • Keep each pull request to one topic, and keep it small.
  • Never commit to your fork’s main for a contribution. Use a branch.
  • Be patient. Maintainers are often volunteers with other work.
Common mistake: working on a stale fork

Working for days on an old copy and only then discovering that the project moved on. Fetch from upstream before you start and again before you open the pull request.

A stand-in for the fork button

The fork here is a bare repository on the same computer, and the names, files and change are made up. On GitHub the fork button, the sync button and the pull request page use their own wording, which changes over time. Check its current help pages.

Practise the whole loop in a scratch folder: make an upstream, a fork and a clone, add the upstream remote, make a change on a branch, let the upstream move, and sync.

Practice for this lesson

Check what you learned

Five quick questions. Pick an answer and you will see straight away whether it is right and why.

What is a fork?

  1. A kind of branch name
  2. A deleted commit
  3. Your own copy of a whole repository under your own account
  4. A local backup

It lets you change a project you cannot write to.

Which remote usually points at your fork?

  1. origin
  2. upstream
  3. main
  4. tags

You add upstream yourself for the original project.

Why keep your fork’s main clean and use a branch for each change?

  1. Git forces it
  2. It stays a mirror of the original and keeps each contribution separate
  3. Branches are free of charge
  4. Main cannot be edited

Asha made fix-tuesday for her change.

What does git fetch upstream do?

  1. Pushes your branch to the original
  2. Deletes your fork
  3. Merges two branches
  4. Downloads the original’s news without changing your files

It is always safe to run.

Where is the pull request opened for a fork contribution?

  1. From main to your fork
  2. From your branch on your fork to the original’s main
  3. Inside the terminal only
  4. It is not needed

The base is the original and the head is your change branch.

Summary

  • A fork is your own copy of a project you cannot write to.
  • origin is your fork; upstream is the original, added by you.
  • Fetch from upstream, merge into main, push to your fork, then update your branch.
  • Make one branch per contribution and keep it small.

Next lesson

Lesson 16 publishes a small website from a repository.

Questions

Do I need a fork for my own projects?

No. A fork is for contributing to a project you do not have write access to. For your own work, a branch in the main repository is enough.

How do I keep my fork in step with the original?

Fetch from the upstream remote and merge into your main, as in this lesson. GitHub also offers a button on a fork that syncs it for you.

Can I delete my fork after my pull request is merged?

Usually yes. Your change now lives in the original project, and you can delete the branch or the fork if you no longer need them.

Progress is saved in this browser.