(Continues part 1 and part 2; fork the full text on GitHub)
Forks and Pull Requests
If you have push access to a repository, you can sync your local clone with the remte on GitHub or GitLab directly. But many projects do allow push access only to a select group of people to make sure noone breaks anything. There are some larger collaborative writing projects like this, e.g., the HoTT Book and the Open Logic Text. You may wish to set up a project in such a way, to allow others to use, improve, and contribute to your project but while retaining control. Git is set up for this kind of scenario, it is called the “fork and pull” model of collaboration. In the fork and pull model, your collaorators each work on their own fork of the repository. Forking your repository is easy: both GitHub and GitLab display a fork button on the repository page. Your contributor clicks on that button, and a complete copy of the repository appears in their own GitHub/GitLab user space. If your repository lives at github.com/reader/project
then their fork will live at github.com/collaborator/project
. Instead of cloning the author/project
repository, and pushing to it directly, they clone the collaborator/project
repository and work on that private copy.
The collaborator/project
repository is a complete copy, but it is not automatically kept in sync with reader/project
. If your collaborator wants to have changes to your repository included also in their forks, they have to do this explicitly. If you have forked a repository, e.g., you have your own fork reader/OpenLogic
of the OpenLogicProject/OpenLogic
, you also have to explicitly merge changes into your fork from the original repository. You do this on your local clone on your own computer. Suppose you have cloned the reader/OpenLogic
repository (your own fork) on your computer’s harddrive. It is already set up with a remote, your fork on GitHub. Pulling and pushin usually happen between your local clone and the remote fork reader/OpenLogic
. To sync changes from the original OpenLogicProject/OpenLogic
repository, you have to add it as anoter remote:
git remote add upstream https://github.com/OpenLogicProject/OpenLogic.git
Here upstream
is the traditional name given to the original remote repository (vs. origin
which is the remote repository on your own GitHub account, which happens to be a fork). Of course, the URL will point to whichever upstream repository you want to track.
Now you can tell Git to pull changes, not from the remote origin
but from upstream
, and merge them into your local repository using the command
git pull upstream master
Your local clone of reader/OpenLogic
contains all the changes from the upstream OpenLogicProject/OpenLogic
. To update these changes also in your own fork on GitHub, simply say
git push
Having a copy of a repository, and keeping it up-to-date with the original, “upstream” version, is only half the fun. The real advantage of being able to edit your own /fork/ — rather than just your own /copy/ — is that your additions and corrections can be incorporated back into the source repository. For instance, you might want to correct a typo, help with some copyediting, or, in a collaborative project, contribute additional material. The editors of the source repository may want to retain control over who gets to contribute what, and so they don’t give push access to anyone. But you can work on your own fork, and make those corrections and additions there first.
When you are done, you can send a /pull request/ to the owners of the source repository. GitHub/GitLab remember from which repository your fork was created, and will display if your fork contains changes not in the upstream source repository. Here’s what user gitonaut
sees after they’ve added some material to their fork of this file:
When your fork is “ahead” of the original repository, you can send a /pull request/: alert the owners of the source repository that your fork contains changes which they might want to pull, i.e., merge into their repository.
The pull request shows up as an “issue” in the GitHub view of the source repository. The owners of the original repository can see who sent the pull request, read the description, look at the line-by-line changes in all affected files. For instance, the pull request adding a paragraph above in this file by gitonaut
looked like this:
The repository owners can respond to the pull request with a comment, e.g., asking for clarification or explaining why they can’t merge the proposed changes. It is also possible to add comments to individual lines in the commits making up the pull request. If the changes in the pull request are simple and do not conflict with any changes that have meanwhile been made to the source repository, GitHub will show a button that allows the repository owner to merge the changes automatically. Your contribution can be easily incorporated into the repository in this way. The history of the files you changed will contain a record of the change merged via the pull request, and you will be listed among the contributors to the files you changed. For instance, this file now lists gitonaut
as a contributor, and the “blame” view of the file shows the contributions made by gitonaut
.