Skip to content
Tutorials Center
My learning

Topics

Lesson 8 of 36 ยท Repositories and Collaboration

Forks and Keeping Up With Upstream

Learn what a fork is, when to fork instead of branch, how to add an upstream remote, sync your fork with the original repository and contribute changes back safely.

When you want to change a project you do not have write access to, you cannot push a branch to it. A fork solves that: it is your own copy of the repository, on your account, that remembers where it came from. You push to your fork, then ask the original maintainers to pull your changes in with a pull request. This is how most open-source contributions work.

Fork versus clone versus branch

These three words are easy to mix up:

Term What it is Where it lives
Clone A copy of a repository on your computer Your disk
Branch A line of development inside one repository Same repository
Fork A new repository on GitHub linked to the original Your GitHub account

If you have write access (you are a collaborator or organization member), you normally just create a branch in the shared repository. Fork when you do not have write access, or when you want an independent copy that might diverge.

Forking

Open the repository and click Fork at the top right. Choose the owner (your account or an organization), keep or change the name, and decide whether to copy only the default branch (a good default). GitHub creates github.com/<you>/<repo> with a note under the title: "forked from owner/repo".

Then clone your fork, not the original:

Terminal
git clone [email protected]:YOU/hello-world.git
cd hello-world
git remote add upstream https://github.com/octo-org/hello-world.git
git remote -v

You now have two remotes:

  • origin your fork (you can push here).
  • upstream the original (read-only for you; you only fetch from it).

(gh repo fork octo-org/hello-world --clone does all of this in one step.)

flowchart LR
  U["upstream<br/>octo-org/hello-world"] -- "fork" --> F["origin<br/>YOU/hello-world"]
  F -- "git clone" --> L["Local clone"]
  U -- "git fetch upstream" --> L
  L -- "git push origin" --> F
  F -- "pull request" --> U

Changes travel: upstream to local (fetch), local to your fork (push), fork to upstream (pull request).

The contribution cycle

  1. Sync your default branch with upstream (below).
  2. Branch: git switch -c fix/typo-in-readme.
  3. Edit and commit. Keep the change small and focused.
  4. Push to your fork: git push -u origin fix/typo-in-readme.
  5. Open a pull request from your branch to the upstream's default branch. GitHub shows a banner on your fork right after you push.
  6. Respond to review; push more commits to the same branch and the pull request updates itself.

Read CONTRIBUTING.md first: many projects ask you to open an issue before large changes, require signed-off commits, or have a particular commit message style.

Syncing your fork

Upstream keeps moving. There are two ways to catch up.

On GitHub: on your fork's page, if your branch is behind, a Sync fork button appears. Update branch merges upstream changes with a fast-forward when possible; if you have your own commits on that branch it may offer to discard them, so use it on a branch you do not commit to directly.

On the command line, which is more flexible:

Terminal
git fetch upstream
git switch main
git merge --ff-only upstream/main     # or: git rebase upstream/main
git push origin main

--ff-only refuses to create a merge commit, so it fails loudly if your main has diverged. That is a feature: keep your own work on feature branches and leave main as a clean mirror of upstream.

To bring a feature branch up to date:

Terminal
git switch fix/typo-in-readme
git rebase upstream/main        # replays your commits on top
git push --force-with-lease     # needed after a rebase; safer than --force
JS Stand-in: is my fork behind?

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

No output.

Fork details worth knowing

  • Visibility and ownership: a fork of a public repository can be public, and you cannot make it private unless the upstream is private. Forks of private repositories stay private and count against the organization's policy.
  • Detaching: to turn a fork into a standalone project you ask GitHub support or use an import; for most uses just keep it as a fork.
  • Network graph: Insights > Forks lists everyone who forked a repository.
  • Actions in forks: workflows do not run automatically in a new fork until you enable them, and secrets of the upstream repository are not available to workflows triggered from fork pull requests, for security.
  • Maintainer edits: when you open a pull request, Allow edits from maintainers lets the maintainers push small fixes to your branch.
JS Stand-in: which remote for which command?

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

No output.

Check your understanding

Quick check ยท 4 questions

of 4 answered You scored / 4 ยท perfect!

  1. 1. When should you fork rather than create a branch?

    Without write access you cannot push branches upstream, so you work in your own fork and open a pull request.
  2. 2. In a fork workflow, which remote is conventionally named upstream?

    origin is your fork; upstream is the project you forked from.
  3. 3. Why use git merge --ff-only upstream/main on your main branch?

    It keeps main as a clean mirror and warns you when it is not.
  4. 4. After rebasing a branch that is already on your fork, how do you update it?

    Rebasing rewrites commits, so a normal push is rejected; --force-with-lease overwrites only if nobody else pushed.

Summary

  • A fork is your own GitHub copy of someone else's repository; clone the fork, not the original.
  • Add an upstream remote and sync with git fetch upstream plus a fast-forward merge or rebase.
  • Work on feature branches, push to origin, then open a pull request to upstream.
  • Check CONTRIBUTING.md, allow maintainer edits, and prefer --force-with-lease after rebases.

Next: Collaborators and Permissions