Forks: your own copy of someone else's repository

A fork is a copy of someone else's repository made under your own GitHub account, one that you are allowed to write to.

The difference from a clone is where the copy appears. git clone brings the project onto your disk, a fork creates a copy on the server under your name. Neither replaces the other: normally you do both, the fork first and then a clone of your fork.

You need it wherever you are not allowed to write to the original. An open project is visible to everyone, but the right to push belongs to the maintainers, and your push into their repository ends in a refusal. In your own fork you are the owner, and you offer the finished change through a pull request.

The full cycle

Press Fork on the page of the original. A few seconds later the copy shows up at github.com/your-login/some-project.
Clone your fork, not the original.
Add the original as a second remote under the name upstream.
Start a branch for the task, do the work, push the branch to your fork.
Open a pull request. GitHub knows the repository is a fork and fills in the original as base and your branch as compare. Check that pair with your own eyes and press Create pull request.

Steps two and three in the terminal:

$ git clone git@github.com:my-login/some-project.git
$ cd some-project
$ git remote add upstream git@github.com:original-owner/some-project.git
$ git remote -v
origin	git@github.com:my-login/some-project.git (fetch)
origin	git@github.com:my-login/some-project.git (push)
upstream	git@github.com:original-owner/some-project.git (fetch)
upstream	git@github.com:original-owner/some-project.git (push)

origin is your fork, that is where you write. upstream is the original, that is where you take updates from. The name upstream is a convention and nothing in git depends on it; remotes themselves are covered in git remote.

Step four is no different from working in a project of your own:

$ git switch -c fix-typo-in-readme
$ git commit -am "Fix typo in the install section"
$ git push -u origin fix-typo-in-readme

Pulling updates from the original

A fork does not update itself. While you work on your change the original moves ahead, and catching up is your job:

$ git fetch upstream
From github.com:original-owner/some-project
 * [new branch]      main       -> upstream/main

$ git switch main
$ git merge upstream/main
Updating 19ab236..efab511
Fast-forward
 README.md | 1 +
 1 file changed, 1 insertion(+)

A plain git push then sends the updated main to your fork. The Sync fork button on the fork's page does the same thing.

Common mistakes

Working straight in the main of your fork. With one task it looks fine, with the second one it turns into a mess: both changes sit in the same branch, and the pull request drags both into the original at once. Give every task its own branch and keep main in the fork a clean copy of the original.

Forgetting about upstream. A month later your copy is a hundred commits behind, your branch is taken from a stale state, and instead of one tidy change you get conflicts all over the project. Run git fetch upstream before you start a new branch.

Where this is in the book

Chapter 7. How teams actually use git.