What is a Pull Request?

Pull Requests (or PRs) allow people to collaborate in Git land. Thanks to them, project maintainers can be notified that there is new code that should be reviewed before (possibly) being integrated into the main project.

Developers rely on pull requests when they don't have "write access" to a repository (such as open-source projects) or when they simply need someone to review their work.

PRs are not just about code reviews, though — they can trigger conversations among collaborators, enabling anyone to provide feedback for the proposed feature/modification, and even enhance it with follow-up commits.

While this activity could be achieved with notification emails, it's much more common (and convenient) to use a cloud-based hosting service, such as GitHub, Bitbucket, GitLab or Azure DevOps.

If you don't have a favorite yet, or if you don't know which is the best platform for your specific needs, have a look at our comparison of Git hosting services. All these tools provide intuitive web interfaces that enable people to comment on the progress made, mention individual participants, and add labels or milestones.

When everyone is happy with the proposed changes, the pull request can finally be merged into the project's main branch.

How Does a Pull Request Work?

A pull request is, essentially, a feature branch — it simply contains some additional meta-information on top of it, such as comments and code reviews. What you're doing with a pull request is asking someone to pull a branch from your repository into theirs.

In order to create a pull request, you have a puzzle with 4 pieces: the source repository, the source branch, the destination repository, and the destination branch. They always require either two distinct branches or two distinct repositories.

The workflow is usually similar to this:

1. A developer works on the feature in a dedicated branch, in their local repository.
2. The developer pushes his work to a public repo, with the help of a remote hosting platform (such as GitHub).
3. The developer creates a pull request using the remote hosting platform's web interface.
4. The project maintainer is notified that there is a new pull request.
5. The team reviews the code and discusses the proposed changes.
6. The feature is merged into the official repository by the project maintainer.
7. The pull request is closed by the project maintainer.

Creating a Pull Request

In this example, we will contribute to an open-source project that we don't have "write access". We will use GitHub, but all other remote hosting platforms work in a similar way.

Start by forking the project you would like to work on. After cloning the repository, create a branch to work on your changes and commit them. Finally, push those changes so that your branch is now present in your remote repository as well.

Now, head back to your branch on GitHub. A yellow notification will prompt you to compare your changes and create a new pull request.

After clicking that button, two actions need to be performed.

First, double check if the "base repository" is the repository you forked (the original project) and that the "head repository" is your own, as shown in the image below. GitHub will also let you know if your work can be merged without any conflicts.

Finally, add your pull request information (title and description) and review what changed.

You're all set to create your first PR! If you're contributing to open source, make sure to read the project's contributing guidelines and the code of conduct before submitting it.

Learn More

• For a pratical example, check out the chapter on Pull Requests in our free online book
• More frequently asked questions about Git & version control