In this article by Achilleas Pipinellis, the author of the book GitHub Essentials, has come up with a workflow based on the features it provides and the power of Git. It has named it the GitHub workflow (https://guides.github.com/introduction/flow).
In this article, we will learn how to work with branches and pull requests, which is the most powerful feature of GitHub.
(For more resources related to this topic, see here.)
Learn about pull requests
Pull request is the number one feature in GitHub that made it what it is today. It was introduced in early 2008 and is being used extensively among projects since then.
While everything else can be pretty much disabled in a project’s settings (such as issues and the wiki), pull requests are always enabled.
Why pull requests are a powerful asset to work with
Whether you are working on a personal project where you are the sole contributor or on a big open source one with contributors from all over the globe, working with pull requests will certainly make your life easier.
I like to think of pull requests as chunks of commits, and the GitHub UI helps you visualize clearer what is about to be merged in the default branch or the branch of your choice. Pull requests are reviewable with an enhanced diff view. You can easily revert them with a simple button on GitHub and they can be tested before merging, if a CI service is enabled in the project.
The connection between branches and pull requests
There is a special connection between branches and pull requests. In this connection, GitHub will automatically show you a button to create a new pull request if you push a new branch in your repository. As we will explore in the following sections, this is tightly coupled to the GitHub workflow, and GitHub uses some special words to describe the from and to branches. As per GitHub’s documentation:
The base branch is where you think changes should be applied, the head branch is what you would like to be applied.
So, in GitHub terms, head is your branch, and base the branch you would like to merge into.
Create branches directly in a project – the shared repository model
The shared repository model, as GitHub aptly calls it, is when you push new branches directly to the source repository. From there, you can create a new pull request by comparing between branches, as we will see in the following sections.
Of course, in order to be able to push to a repository you either have to be the owner or a collaborator; in other words you must have write access.
Create branches in your fork – the fork and pull model
Forked repositories are related to their parent in a way that GitHub uses in order to compare their branches. The fork and pull model is usually used in projects when one does not have write access but is willing to contribute.
After forking a repository, you push a branch to your fork and then create a pull request in the source repository asking its maintainer to merge the changes. This is common practice to contribute to open source projects hosted on GitHub. You will not have access to their repository, but being open source, you can fork the public repository and work on your own copy.
How to create and submit a pull request
There are quite a few ways to initiate the creation of a pull request, as we you will see in the following sections.
The most common one is to push a branch to your repository and let GitHub’s UI guide you. Let’s explore this option first.
Use the Compare & pull request button
Whenever a new branch is pushed to a repository, GitHub shows a quick button to create a pull request. In reality, you are taken to the compare page, as we will explore in the next section, but some values are already filled out for you.
Let’s create, for example, a new branch named add_gitignore where we will add a .gitignore file with the following contents:
git checkout -b add_gitignore
echo -e '.bundlen.sass-cachen.vendorn_site' > .gitignore
git add .gitignore
git commit -m 'Add .gitignore'
git push origin add_gitignoreNext, head over your repository’s main page and you will notice the Compare & pull request button, as shown in the following screenshot:
From here on, if you hit this button you will be taken to the compare page. Note that I am pushing to my repository following the shared repository model, so here is how GitHub greets me:
What would happen if I used the fork and pull repository model? For this purpose, I created another user to fork my repository and followed the same instructions to add a new branch named add_gitignore with the same changes. From here on, when you push the branch to your fork, the Compare & pull request button appears whether you are on your fork’s page or on the parent repository.
Here is how it looks if you visit your fork:
The following screenshot will appear, if you visit the parent repository:
In the last case (captured in red), you can see from which user this branch came from (axil43:add_gitignore).
In either case, when using the fork and pull model, hitting the Compare & pull request button will take you to the compare page with slightly different options:
Since you are comparing across forks, there are more details. In particular, you can see the base fork and branch as well as the head fork and branch that are the ones you are the owner of.
GitHub considers the default branch set in your repository to be the one you want to merge into (base) when the Create Pull Request button appears.
Before submitting it, let’s explore the other two options that you can use to create a pull request. You can jump to the Submit a pull request section if you like.
Use the compare function directly
As mentioned in the previous section, the Compare & pull request button gets you on the compare page with some predefined values. The button appears right after you push a new branch and is there only for a few moments. In this section, we will see how to use the compare function directly in order to create a pull request.
You can access the compare function by clicking on the green button next to the branch drop-down list on a repository’s main page:
This is pretty powerful as one can compare across forks or, in the same repository, pretty much everything—branches, tags, single commits and time ranges.
The default page when you land on the compare page is like the following one; you start by comparing your default branch with GitHub, proposing a list of recently created branches to choose from and compare:
In order to have something to compare to, the base branch must be older than what you are comparing to.
From here, if I choose the add_gitignore branch, GitHub compares it to a master and shows the diff along with the message that it is able to be merged into the base branch without any conflicts. Finally, you can create the pull request:
Notice that I am using the compare function while I’m at my own repository. When comparing in a repository that is a fork of another, the compare function slightly changes and automatically includes more options as we have seen in the previous section.
As you may have noticed the Compare & pull request quick button is just a shortcut for using compare manually. If you want to have more fine-grained control on the repositories and the branches compared, use the compare feature directly.
Use the GitHub web editor
So far, we have seen the two most well-known types of initiating a pull request. There is a third way as well: using entirely the web editor that GitHub provides. This can prove useful for people who are not too familiar with Git and the terminal, and can also be used by more advanced Git users who want to propose a quick change.
As always, according to the model you are using (shared repository or fork and pull), the process is a little different. Let’s first explore the shared repository model flow using the web editor, which means editing files in a repository that you own.
The shared repository model
Firstly, make sure you are on the branch that you wish to branch off; then, head over a file you wish to change and press the edit button with the pencil icon:
Make the change you want in that file, add a proper commit message, and choose Create a new branch giving the name of the branch you wish to create. By default, the branch name is username-patch-i, where username is your username and i is an increasing integer starting from 1. Consecutive edits on files will create branches such as username-patch-1, username-patch-2, and so on. In our example, I decided to give the branch a name of my own:
When ready, press the Propose file change button. From this moment on, the branch is created with the file edits you made. Even if you close the next page, your changes will not be lost. Let’s skip the pull request submission for the time being and see how the fork and pull model works.
The fork and pull model
In the fork and pull model, you fork a repository and submit a pull request from the changes you make in your fork. In the case of using the web editor, there is a caveat. In order to get GitHub automatically recognize that you wish to perform a pull request in the parent repository, you have to start the web editor from the parent repository and not your fork. In the following screenshot, you can see what happens in this case:
GitHub informs you that a new branch will be created in your repository (fork) with the new changes in order to submit a pull request. Hitting the Propose file change button will take you to the form to submit the pull request:
Contrary to the shared repository model, you can now see the base/head repositories and branches that are compared. Also, notice that the default name for the new branch is patch-i, where i is an increasing integer number. In our case, this was the first branch created that way, so it was named patch-1.
If you would like to have the ability to name the branch the way you like, you should follow the shared repository model instructions as explained in preceding section. Following that route, edit the file in your fork where you have write access, add your own branch name, hit the Propose file change button for the branch to be created, and then abort when asked to create the pull request. You can then use the Compare & pull request quick button or use the compare function directly to propose a pull request to the parent repository.
One last thing to consider when using the web editor, is the limitation of editing one file at a time. If you wish to include more changes in the same branch that GitHub created for you when you first edited a file, you must first change to that branch and then make any subsequent changes. How to change the branch? Simply choose it from the drop-down menu as shown in the following screenshot:
Submit a pull request
So far, we have explored the various ways to initiate a pull request. In this section, we will finally continue to submit it as well.
The pull request form is identical to the form when creating a new issue. If you have write access to the repository that you are making the pull request to, then you are able to set labels, milestone, and assignee.
The title of the pull request is automatically filled by the last commit message that the branch has, or if there are multiple commits, it will just fill in the branch name. In either case, you can change it to your liking. In the following image, you can see the title is taken from the branch name after GitHub has stripped the special characters. In a sense, the title gets humanized:
You can add an optional description and images if you deem proper. Whenever ready, hit the Create pull request button. In the following sections, we will explore how the peer review works.
Peer review and inline comments
The nice thing about pull requests is that you have a nice and clear view of what is about to get merged. You can see only the changes that matter, and the best part is that you can fire up a discussion concerning those changes.
In the previous section, we submitted the pull request so that it can be reviewed and eventually get merged. Suppose that we are collaborating with a team and they chime in to discuss the changes. Let’s first check the layout of a pull request.
Summary
In this article, we explored the GitHub workflow and the various ways to perform a pull request, as well as the many features GitHub provides to make that workflow even smoother. This is how the majority of open source projects work when there are dozens of contributors involved.
Resources for Article:
Further resources on this subject:
- Git Teaches – Great Tools Don’t Make Great Craftsmen[article]
- Maintaining Your GitLab Instance[article]
- Configuration [article]
