We’ve made a change to our fork of the project, but the change hasn’t propagated
back to the original project. That makes sense. Anyone can fork any public project,
and the project owner wouldn’t want just anyone editing all of their files.
However, sometimes it’s great to allow other people to propose changes to a project. This allows a large number of people to easily contribute to an open source project or a smaller
team to work together on an internal project.
That is what pull requests are for. With a pull request, you can request that changes you’ve made on a fork be incorporated into the original project. Let’s go through the process now. As you can see in this pic, on the right side of the page there is a Pull Requests tab.
Click the Pull Requests tab, and you’ll see a screen similar showing that currently you don’t have any outstanding pull requests. Click the green “New pull request” button at the top right of the screen.
When you click the button, you’ll see a screen similar to.
One of the first things you see in The “preview pull request” screen is that it is proposing a pull request between pragmaticlearning:master and PeterBell:master. Pull requests are requests to incorporate the changes from one branch (stream of history) into another.
In this case, GitHub has correctly guessed that I want to take the change that I made on the master branch on my fork (the new file I added) and have that merged back into the
master branch on the original project that I forked from.
Note that the branch with the changes that you simply want merged in is on the proper , and therefore the target branch you’d like it to be merged into is on the left.
As you look lower down on The “preview pull request” screen, you’ll also see that it provides a summary of the changes that might occur if that pull request was merged—I did indeed make one commit that changed a single file.
It even shows in green the new content that would be added to new_file.md. If I click the “Show diff stats” button, it would even show numerically that one line of content was being added and no lines of content were being removed.
Once we’ve confirmed that the proposed pull request is the one we want to create, the
next step is to click the massive green “Create pull request” button. Doing so will take
you to a page similar to The “create pull request” screen.
This screen is your chance to tell the story about why your changes should be incorporated in the other project, so take the time to create a meaningful title and description of the changes you’ve made.
By default the title will be the first line of your commit message for your most up-to-date commit, and if you’ve made quite one commit on the branch you’re trying to have merged, the description will have a bulleted list of the first line of all of the commit messages that are part of the pull request.
That’s a fine starting point, but you’re going to want to take a little bit of time to
describe not only what changes you’ve made, but why you made them and why they’d
be a good addition to the project.
Once you’ve finished describing your pull request, click the “Create pull request” but‐
ton and you’ll see a page that looks like A created pull request.
There are a couple of things that you should notice in A created pull request. First, notice that we’re now in the original project—under pragmaticlearning.
This makes sense. We wanted to create a request to pull our work into that project, so the pull request is part of that project—not our fork. You can see that “PeterBell wants to merge 1 commit into pragmaticlearning:master from PeterBell:master,” and it shows you the pull request (title and description) followed by the commit that was made.
Clicking that commit displays the details of the commit, as you can see in Viewing the commit from the pull request.
Notice that the commit link has taken us back to the PeterBell version of the repo
because that is where the commit was made. It shows you the commit message, who
made the change, and the changes that were introduced in that commit.
Going back to the pull request in A created pull request, you’ll see that there is an option to merge the pull request.
That option is visible only to the owner of the project or to anyone the owner has added as collaborators. If someone without those permissions was watching the page, he wouldn’t be ready to merge the pull request.
in Viewing a pull request without being able to merge it I’ve logged in as another user, and when I view the same page, I don’t get the choice to merge within the pull request, although I can still discuss it if I want.
I’m just going to accept the pull request and merge it in. I can just click the “Merge pull request” button, which adds a text box where I get the option to customize the commit message for merging the pull request, as shown in Getting ready to merge a pull request
Once I’ve made any changes I want to the commit message, I can just click the “Con‐
firm merge” button below and to the right. The pull request is then merged, and the
output is displayed, as in Viewing a closed (merged) pull request.
Notice that we can still see the pull request message and the commit, but now we can
also see who merged in the pull request and approximately when they did so. It also
shows that the pull request was closed, which happens automatically when you merge
it. Finally, if we look at the project page in The original (pragmaticlearning) project after merging the pull request, we’ll notice a couple of things.
First, new_file.md has been added to the project. Second, there are four commits now
in the original project. If we click the “4 commits” link, we can see why (see The original project commit history)
There were the two original commits in the project, there is the “Create new_file.md”
commit that was made on my fork, and there is a new merge commit that brought the
work into the original project when we merged the pull request.
Whenever you merge a pull request, it’ll create one among these merge commits. They are really useful because the commit message (which you’ll edit once you merge a pull request) allows you to document why you decided to include the work; if you ever wanted to get rid of all of the work you merged in from a pull request, you could ask one of your
developers to “revert the merge commit for that pull request” and she’d be ready to
easily remove all of the changes that got merged in.
If you like this post, don’t forget to share 🙂