Digital Scholarship Resources - Vanderbilt Libraries Digital Scholarship and Communications Office

previous page: managing projects

Forking a Repo and the Open Source Model

The last major concept in working with GitHub is forking a repository. When you fork a repository, you are making your own personal copy of a repository that is part of a different organization or person’s account. Your fork (fork is both a noun and verb) of the repository is completely independent of the source repository, and changes you make to the fork have no effect on the original repository unless you use a pull request to merge your changes back into it.

forking

There are two major reasons why you might want to fork someone else’s repo. One is to simply get a copy of the repo so that you can play with it. In that case, you would fork the repo to your own account on the GitHub website, then use GitHub desktop to clone the repository to your local hard drive. A simpler alternative would be to simply download the foreign repo as a zip file, then open the file somewhere on your hard drive. The advantage of using the fork, then clone approach is that you can use the Git system to switch between branches in the forked repo and also potentially feed edits back to the original repo.

The Open Source Model

The other major reason for forking is as a means to contribute to a project for which you do not have write (i.e. push) access. This is a common situation for large open source projects, where there may be a large number of contributors, some of whom might not even be known to the repository owners.

open source model diagram

In this model, you fork the project repository to your own account using the GitHub website. You can then clone the forked repository to your desktop as you would any other repo. Typically you would create a working branch on the local copy of the repo, edit the documents, then push the changes to GitHub. From the GitHub website, you can then create pull requests asking the repository owners to consider pulling your recommended changes back into the original project. The request can be to pull the changes from a branch of the fork into the master of the organizational repo, although there are other possibilities depending on what’s conventional practice for the organization. In the simplified example below, the online editor is used to directly edit a file on the master of the fork.

Because this process involves forking followed by pull requests, it’s known as the “fork and pull” model of collaboration.

Fork and Pull Example

Let’s imagine a scenario involving me and my alter ego, Tomy the Cat. I’ve started an open source collaborative project called the “Nashville Coding Cats” club and created a repo on my account called “code-cats-rock”. Tomy visits my site and is excited about participating. Here’s what he sees:

After he clicks on the repository name, he clicks on the Fork button at the upper left of the repository summary page.

If he has has push access to multiple accounts, he may need to choose which account to put the fork in.

The fork will now show up as a repository in his own account. To prevent confusion, the a forked repo has a note under it to remind the user that the repo is forked from somewhere else.

At this point, the forked repo will show up on the list of repos that Tomy can clone in GitHub Desktop. Now Tomy has edited the README.md page (either directly on GitHub using the online editor, or on his laptop using the Desktop Client followed by pushing the changes up to GitHub).

Here’s what the forked repo page looks like now:

In order to make a pull reqest, we need to switch from the GitHub site of the forked (head) repo to the GitHub site of the organizational (base) repo. Here’s what the page looks like when we click on the New pull request button (on the organization’s copy of the repo).

Creating a pull request from a fork is a bit more complicated than a pull request from a branch because we can choose to merge from any branch in the forked repository to any branch in any other repository (including another fork) that’s based on the same original repo. In this case the situation is simple, since we are pulling from the master branch in the fork to the master branch in the original repo. If the edits were made in a working branch (more typical for a major development), at this point you would make a selection of the appropriate branch from the dropdowns.

The term head is used for the source branch/repo/account and base is used for the target branch/repo/account. To avoid any confusion, pay attention to the direction that the arrow is pointing in the dropdowns used to select branches and repos. Click the Create pull request button to begin the pull request.

The email generated by the @mention has links to the pull request so the project manager can go straight to it on GitHub.

Clicking on the link in the email takes the project manager to the pull request. The manager can do the merge or make further comments with requests for changes.

After doing the merge, the changes have been added to the original project.

Back in Tomy’s account, he can now decide whether he wants to keep the fork or not. If there isn’t really anything useful for him to do with it (since his changes were pulled into the main project), he can go to the settings for the repo and delete it.

Note that deleting the fork will have no effect on the original repository. Caution: do not delete the fork before the changes have been pulled into the organizational (base) repository! If you do, it will be impossible to complete the merge.

In summary, the process of making pull requests to move changes into the organizational repository from a forked repository is very similar to pulling in changes from a fork within the same repository. The main difference is that there are more options for selecting the repository and forks to be used both at the head and base of the merge.

next page: GitHub Pages websites

FYI for Good Place fans, this is a forking page…

via GIPHY


Revised 2019-10-07

Questions? Contact us

License: CC BY 4.0.
Credit: "Vanderbilt Libraries Digital Scholarship and Communications - www.library.vanderbilt.edu"