Skip to content
Tutorials Center
My learning

Topics

Lesson 38 of 78 ยท Remotes and Collaboration

Forks, Upstreams and Contributing

Learn the fork workflow: what a fork is, adding an upstream remote, syncing your fork, rebasing a pull request, and how maintainers fetch contributions. Runs locally.

On most open-source projects you cannot push to the main repository. That is a feature, not a barrier: the maintainers keep control over what ships, and anybody in the world can still propose a change. The mechanism is the fork. A fork is your own server-side copy of a repository. You push to your copy, then ask the maintainers to pull your work from it.

Forking is a hosting-platform feature (GitHub, GitLab and others have a Fork button), but underneath it is just Git with two remotes: origin, which is your fork, and upstream, which is the original project. In this lesson you will build exactly that setup with local bare repositories, sync your fork when the original moves on, send a contribution, update it when it goes stale, and see the same events from the maintainer's side.

Our sandbox has no network, so the three "servers" below are bare repositories on disk: upstream.git (the original project), fork.git (your fork) and the people's clones. A real platform adds web pages, accounts and pull requests around the same Git commands. The names origin and upstream are conventions, not keywords.

What a fork is, in Git terms

Pressing Fork makes the platform run something close to git clone --bare on its servers: a full copy of the repository, owned by you, with its own branches, tags and permissions. The platform also remembers where it came from, which it uses to show "forked from ..." and to offer pull requests across the two. Git itself does not remember: the connection between a fork and its parent is stored only in the platform's database.

TEXT
        original project (upstream)           your fork (origin)             your laptop
        maintainers can push here             only you can push here

        upstream.git  ---- Fork button ---->  fork.git  ---- git clone ---->  dev/
              ^                                     ^                           |
              |                                     |                           |
              +------ pull request (platform) ------+<------ git push ----------+
              |                                                                 |
              +------------------------ git fetch upstream ---------------------+

You push to origin; you only fetch from upstream (you do not have write access there anyway).

Setting up: clone the fork, add upstream

After forking, you clone your fork (not the original), and then add the original as a second remote. The next example performs the whole setup.

Bash A fork and the two remotes

Press Run (or Ctrl + Enter) to see the result here.

Program input ยท what you'd type while the program runs

Type the answers before you press Run, one per line. Each time the program reads a line (with read or cat), it gets the next line from this box.

git remote -v lists origin (the fork, fork.git) and upstream (../upstream.git). After git fetch upstream the repository holds two sets of remote-tracking branches, origin/main and upstream/main, which is how you can compare your fork with the original at any time. Your local main tracks origin/main (the branch -vv line), because that is what you cloned.

Real URLs look like git clone [email protected]:you/project.git and then git remote add upstream https://github.com/original-owner/project.git. Some people use HTTPS for upstream (read-only, no key needed) and SSH for origin. The GitHub CLI can do the whole setup in one go (gh repo fork --clone); it is read-only knowledge here, but it does exactly the commands above.

Syncing your fork

The original project keeps moving; your fork does not, unless you tell it to. If you never sync, your next contribution starts from an old base and conflicts become likely. The routine is always the same, three steps:

  1. git fetch upstream to download the project's latest commits.
  2. Update your local main to match upstream/main.
  3. git push origin main to bring your fork up to date.

For step 2, if you never commit directly to main (and you should not), a fast-forward only merge is all you need. If it fails, you committed to main by accident, which is worth knowing about.

Bash Syncing a fork with the original

Press Run (or Ctrl + Enter) to see the result here.

Program input ยท what you'd type while the program runs

Type the answers before you press Run, one per line. Each time the program reads a line (with read or cat), it gets the next line from this box.

git rev-list --left-right --count main...upstream/main printed 0 2: my main has nothing the original lacks, and the original has two new commits. The fast-forward merge succeeded, and git push origin main updated the fork. The platforms offer a "Sync fork" button that performs exactly steps 2 and 3 on the server.

If you did commit on main by mistake, do not use git reset --hard upstream/main until you have moved those commits to a branch (git branch rescue). Hard resets discard work; the commits would still be in the reflog, but do not rely on that.

Contributing a change

The contribution cycle, step by step:

  1. Sync your fork (above), so you start from the latest code.
  2. Branch from upstream/main, with one branch per change: git switch -c fix-typo upstream/main. Never work on main.
  3. Read CONTRIBUTING and follow the project's conventions: commit message style, tests, formatting, sign-off. See Contributing to Open Source.
  4. Commit a focused change and push the branch to your fork: git push -u origin fix-typo.
  5. Open a pull request from your fork's branch to the original's main (on the platform).
  6. Respond to review with more commits; update the branch if main moves (Pull Requests and Code Review).

Two settings make the two-remote life smoother. git config remote.pushDefault origin says "a push without a remote name goes to origin", even if the branch tracks upstream. This is called a triangular workflow: you fetch from one place and push to another.

Bash Branch from upstream, push to the fork, rebase when it goes stale

Press Run (or Ctrl + Enter) to see the result here.

Program input ยท what you'd type while the program runs

Type the answers before you press Run, one per line. Each time the program reads a line (with read or cat), it gets the next line from this box.

Look at the first branch -vv line: because the branch was created from upstream/main, Git set [upstream/main] as its upstream. After git push -u origin fix-typo the upstream changed to origin/fix-typo, which is what you want for pushing and for the "ahead/behind" numbers in git status. When upstream/main gained a commit, rev-list showed 1 1: my branch was one ahead and one behind. git rebase upstream/main put my commit on top of the maintainer's, and the push needed --force-with-lease, shown as + ... (forced update): pushing a rebased branch to your own fork is the normal use of force. If you had opened the PR already, it updates automatically.

Last, the maintainer's side: they add your fork as a remote (git remote add dev ../fork.git), fetch it, look at git log main..dev/fix-typo and, since the branch sits directly on top of main, fast-forward and push. On a platform the Merge button does this, with a merge commit, squash or rebase as covered in Pull Requests and Code Review.

Reviewing a pull request locally

Sometimes a maintainer wants to try a contribution before merging. Platforms such as GitHub publish a special ref per pull request (refs/pull/<number>/head) in the base repository, which you can fetch without adding the contributor's fork as a remote. We can fake that ref on a local server to see how it works.

Bash Fetching a pull request by number

Press Run (or Ctrl + Enter) to see the result here.

Program input ยท what you'd type while the program runs

Type the answers before you press Run, one per line. Each time the program reads a line (with read or cat), it gets the next line from this box.

git ls-remote listed refs/pull/7/head next to HEAD and the branches: the server keeps a ref for the pull request even though no branch exists. git fetch origin pull/7/head:pr-7 is a refspec (source:destination, see Transfer Protocols) that downloaded it into a local branch pr-7, which you can build, test and review. The extra remote.origin.fetch line makes every future git fetch collect all PRs as origin/pr/<n>, handy for maintainers. (In this simulation, GitHub's actual layout of pull/N/head is mimicked; GitLab uses merge-requests/N/head.)

Good citizenship in open source

  • Read before writing: README, CONTRIBUTING, CODE_OF_CONDUCT and the issue tracker. Ask in an issue before starting a large change.
  • One topic per branch and PR. Maintainers merge small, focused changes much faster.
  • Rewrite only your own branch. Rebasing and force-pushing your PR branch is fine; rewriting commits that someone else has based work on is not.
  • Keep your fork's main clean so it is a faithful mirror of upstream.
  • Mind the maintainer's time. They are often volunteers. Be patient, polite and responsive, and accept "no" gracefully.

For maintainers: use branch protection, require CI, label issues such as "good first issue", document the workflow, and merge with the method that keeps your history readable. If a contributor's PR conflicts after main moved, you can ask them to rebase, or, if the project allows maintainers to edit PR branches, do it yourself.

Contributions inside a company often work the same way, with one shared repository and branches instead of forks; see Collaboration Workflows for when each model fits.

Check your understanding

Quick check ยท 5 questions

of 5 answered You scored / 5 ยท perfect!

  1. 1. In the usual fork setup, which remote is your own fork?

    You clone your fork, so it becomes origin. The original project is added as a second remote, conventionally named upstream.
  2. 2. Which command sequence brings your fork's main up to date with the original project?

    Fetch the original's commits, update your local main (fast-forward), then push it to your fork. Pulling from origin would not bring in new upstream commits.
  3. 3. Why should you create a branch for each contribution instead of committing on main?

    Keeping main identical to upstream makes syncing trivial (fast-forward), and one branch per change lets you update, rebase or abandon each PR independently.
  4. 4. Your PR branch has gone stale after upstream/main advanced. You rebased it onto upstream/main. How do you update the PR?

    The rebase rewrote your commits, so you must force-push (with a lease) to your own fork. The open pull request then shows the new commits automatically.
  5. 5. What does git fetch origin pull/7/head:pr-7 do?

    It is a fetch with the refspec source:destination. Nothing is merged or pushed; you get a local branch to inspect and test.

Summary

  • A fork is your own server-side copy of a repository; the link to the parent exists only on the hosting platform.
  • Clone your fork as origin, add the original as upstream, and fetch from upstream regularly.
  • Sync with git fetch upstream, git merge --ff-only upstream/main on main, then git push origin main.
  • One branch per change, started from upstream/main; push it to origin and open a pull request.
  • A stale PR is fixed by rebasing onto upstream/main and force-pushing with a lease to your own fork.
  • remote.pushDefault and branch upstream settings make fetch-from-one, push-to-another (triangular) workflows smooth.
  • Maintainers can fetch contributions from a fork remote or from platform PR refs such as refs/pull/N/head.

Next: Submodules, Subtrees and Monorepos