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
mainfor a contribution. Use a branch. - Be patient. Maintainers are often volunteers with other work.
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.
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.
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?
- A kind of branch name
- A deleted commit
- Your own copy of a whole repository under your own account
- A local backup
It lets you change a project you cannot write to.
Which remote usually points at your fork?
- origin
- upstream
- main
- tags
You add upstream yourself for the original project.
Why keep your fork’s main clean and use a branch for each change?
- Git forces it
- It stays a mirror of the original and keeps each contribution separate
- Branches are free of charge
- Main cannot be edited
Asha made fix-tuesday for her change.
What does git fetch upstream do?
- Pushes your branch to the original
- Deletes your fork
- Merges two branches
- 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?
- From main to your fork
- From your branch on your fork to the original’s main
- Inside the terminal only
- 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.
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.
