The goal of open source is to encourage collaboration among software developers around the world, so being able to contribute code to repositories where you aren’t the owner or an explicit collaborator is an important part of the GitHub workflow and mission. To become a collaborator of an open source project, you can reach out to the owner of the repo and request to be a collaborator. However, if the owner doesn’t know who you are, they probably won’t add you as a collaborator because that would give you push rights to the repository. You’ll have to gain their trust first.
You don’t need the owner’s permission to fork their repository. You can make your contributions and share them with the owner to show how you can be an asset to the project.
To fork a repo, go to the repo home page and click the Fork button at the top right. If you’d like, you can use https://github.com/thewecanzone/ GitHubForDummiesReaders to practice forking and contributing to a public repo.
After you click the Fork button, the web page refreshes, and you see a slightly modified version of the repo, as shown in Figure 6-2. At the top of the repo, you see that the repo is attached to your account, but it still has a reference to the original repo.
If you’re part of multiple GitHub organizations, you’re asked to choose which organization you want to fork the repository to after you click the Fork button and before the web page refreshes.
After you have your own, forked version of the repo, you can clone it on your local machine to start making changes. Chapter 7 goes over writing code and creating commits, which is the same process whether you’re on a forked repo or a regular
repo. If you clone the repo using GitHub Desktop, your local git repository knows about your forked version (remote origin) and the original repo (remote upstream).
The concept of a remote can be confusing to those new to distributed version control systems like Git. When you clone a GitHub repository, you have a full copy of the repository on your local machine. You may be tempted to think the copy of the repository on GitHub is the canonical copy. However, there is no concept of canonical in Git. The canonical copy is whatever the people working on the project decide it is by consensus. Git does have the concept of a remote, which is a pointer to a copy of the same Git repository hosted elsewhere. Typically, a remote is a URL to a Git-hosting platform like GitHub, but it’s possible to be a path to a directory with a copy of the repository. When you clone a repository, Git adds a remote named origin with the location (usually a URL) from where you cloned it. But it’s possible to add multiple remotes to a Git repository to indicate other locations where you may want to push and pull changes from. For example, if you clone a fork of a repository, you may want to have a remote named upstream that points to the original repository.
If you clone the repo using the command line, you may want to set the upstream remote, which we explain in the section “Getting unstuck when cloning without forking,” later in this chapter. You can see both the forked remote origin and original remote upstream if you run the git remote -v command in the directory where you cloned the repo:
$ git remote -v
origin https://github.com/sarah-wecan/
GitHubForDummiesReaders.git (fetch)
origin https://github.com/sarah-wecan/
GitHubForDummiesReaders.git (push)
upstream https://github.com/thewecanzone/
GitHubForDummiesReaders.git (fetch)
upstream https://github.com/thewecanzone/
GitHubForDummiesReaders.git (push)
The origin, which is where you fetch/pull changes from and push changes to, has your username (sarah-wecan in this example). The upstream, which is where the original code is located, and where you eventually want to contribute the code you write back to, has the original author’s username (thewecanzone in this example).
1. Fetching changes from upstream
Having the upstream repo linked to your forked repo is important. As you start making changes, you want to be able to fetch/pull any changes that are being made on the original code into your code to make sure that you have the most up-to-date version.
For example, suppose that you forked and cloned a website project a week ago with plans to change the website’s About page. While you were working on those changes, someone else made a change to the About page. Their changes may conflict with your changes, or they may introduce something new that you want to use in your changes. Pulling those changes into your local repository before you submit your changes back to the original repository makes sense. It reduces the chance that your changes conflict with the changes others are making to the About page and makes it more likely the owner can accept them.
If you find yourself in a situation where you need to get the change from the upstream, original repo, you can go to the directory where your forked repo is and type
$ git fetch upstream
remote: Enumerating objects: 5, done.
remote: Counting objects: 100% (5/5), done.
remote: Compressing objects: 100% (3/3), done.
remote: Total 3 (delta 1), reused 0 (delta 0), pack-reused 0
Unpacking objects: 100% (3/3), done.
From https://github.com/thewecanzone/GitHubForDummiesReaders
8404f3b..e02a4d2 master -> upstream/master
$ git checkout -b new-branch
Switched to a new branch ‘new-branch’
$ git merge upstream/master
Updating 8404f3b..e02a4d2
Fast-forward
README.md | 2 +1 file changed, 1 insertion(+), 1 deletion(-)
These three commands fetch the changes from the upstream repo, ensure that you’re on your local, forked repo on a new branch, and then merges the changes from the upstream repo into your forked repo.
2. Contributing changes to upstream
After you make changes and publish them to a new in your forked repository, you’re ready to suggest your changes to the original owner. If you go to the original, upstream repo on GitHub.com, your branch shows up on the home page, and GitHub asks whether you want to open a pull request to merge the changes with the original repo (see Figure 6-3).
On your forked repo on GitHub.com, your branch shows up, and GitHub asks whether you want to create a pull request for it (see Figure 6-4).
Click the Compare & pull request button, and a pull request creation page gives you the option to request to merge your changes with the upstream repo or your forked repo (see Figure 6-5). Choose the upstream repo, add a comment, and click the Create pull request button.
You see that the branch can be merged, but you have no way to personally merge the pull request is because you aren’t the owner of the target branch (upstream, original repo); only the owner (or a specified collaborator) has permission to merge code. Figure 6-6 shows the pull request on your repo without the option to merge.
As the owner of the upstream, original pull request, I can see the pull request and have the option to merge it (see Figure 6-7). If you’re creating a pull request on this repo, I will continually merge pull requests so that we can keep an up-to-date table of all the GitHub For Dummies readers!
TIP: If you have a lot of changes that you want to add to your fork before requesting that they get merged into the upstream, original repo, then you can first create the pull request to target your forked repo instead of the upstream repo. This is a change in what is shown in Figure 6-5. When you’re ready to merge your changes into upstream, you can create a new pull request to request the target of the merge be the upstream repo.
3. Getting unstuck when cloning without forking
One common problem people run into is they forget to fork a repository before they try to contribute to it. The following scenario describes one example of getting into this situation.
Here’s the scenario: You clone a repository onto your local computer, modify the code, commit changes to master, and are ready to push your changes. But then you get a scary-looking error message. You may get the message in Atom (see Figure 6-8), GitHub Desktop (see Figure 6-9), or in the terminal:
$ git push origin master
remote: Permission to thewecanzone/GitHubForDummiesReaders.git
denied to sarah-wecan.
fatal: unable to access ‘https://github.com/thewecanzone/
GitHubForDummiesReaders.git/’: The requested URL returned
error: 403
The error message tells you that you don’t have permission to push to this repository. You should have forked the repository first. You also made the mistake of committing directly to master. As we recommend elsewhere in the book, it’s a good practice to make all your changes in a branch.
To fix this mistake, you need to move your changes to a new branch, fork the repo, change the remote URLs for your local repository to point to your fork, and push your changes. This process can get tricky, but these steps can help you out of this predicament:
- Migrate your changes to a new branch.
Right when you discover you’re targeting the incorrect remote repository, you should move your changes to a new branch. You don’t want to accidentally pull in changes from the upstream, original branch onto all the hard work you just finished. This step can get tricky, but luckily Phil has created a Git Alias to help.
See the nearby sidebar “Creating a Git Alias” for help. After you have the git migrate alias, go to the directory where your repo is in your terminal and type
$ git migrate new-branch
Switched to a new branch ‘new-branch’
Branch ‘master’ set up to track remote branch ‘master’ from ‘origin’.
Current branch new-branch is up to date.
Confirm that the new branch has been created:
$ git status
On branch new-branch
nothing to commit, working tree clean
You can also confirm that your commits are only in this new branch and no longer in the old branch by running a log command to compare the two branches:
$ git log master..new-branch —oneline
This lists the commits in new-branch that are not in master. The —oneline flag prints each commit on a single line, which is useful when you just need a summary of commits and not the full details.
- Set the upstream remote to be the original repo.
To add an upstream remote to your repo, go to the terminal and type
$ git remote add upstream https://github.com/thewecanzone/
GitHubForDummiesReaders.git
Confirm that the upstream remote was added correctly:
$ git remote -v
origin https://github.com/thewecanzone/
GitHubForDummiesReaders.git (fetch)
origin https://github.com/thewecanzone/
GitHubForDummiesReaders.git (push)
upstream https://github.com/thewecanzone/
GitHubForDummiesReaders.git (fetch)
upstream https: //github. com/thewecanzone/
GitHubForDummiesReaders.git (push)
- Fork the repo.
Back on GitHub.com, go to the original repo and click Fork at the top right of the repo home page. The page refreshes, and you see your own version of the repo, referencing the original repo (refer to Figure 6-2, earlier in the chapter).
- Set the origin remote to be your forked repo.
After you have your own fork of the repo, you can change your remote origin to be your version:
$ git remote set-url origin https://github.com/sarah-wecan/
GitHubForDummiesReaders.git
You can also confirm that all your remote URLs are correctly set:
$ git remote -v
origin https://github.com/sarah-wecan/
GitHubForDummiesReaders.git (fetch)
origin https://g i thub.com/sarah-wecan/
GitHubForDummiesReaders.git (push)
upstream https: //github. com/thewecanzone/
GitHubForDummiesReaders.git (fetch)
upstream https: //github. com/thewecanzone/
GitHubForDummiesReaders.git (push)
- Push your branch to your forked version.
You’re now in the same state that you would be in had you forked the repo before cloning. Back in Atom, you can publish your branch.
- Create a pull request.
And just like in Figure 6-4, earlier in this chapter, your forked repo detects a new branch and offers to have you create a pull request.
Source: Guthals Sarah, Haack Phil (2019), GitHub for Dummies, Wiley.