What Is a Pull Request? A Complete Guide to PRs

Table of Contents

What Is a Pull Request? A Complete Guide to How PRs Work

What Is a Pull Request?

A pull request (PR) is a formal request to merge changes from one branch of a code repository into another, usually after teammates review them. The author proposes the change, reviewers comment and approve it, and a maintainer merges it into the main codebase.

The name can sound backwards. You are not pulling anything yourself. You are asking the owner of the target branch to pull your work in. That small shift explains the whole idea: a pull request is a conversation about a change, held before the change becomes part of the shared project.

Think of it like editing a shared document with tracked changes. You do not rewrite the original while everyone is reading it. You make your edits in a separate copy, show exactly what changed, and let others comment before the edits are accepted. A pull request does the same for code.

A few terms make the rest of this guide easier to follow:

  • Repository: the project folder and its full history, stored on a platform such as GitHub, GitLab or Bitbucket.
  • Branch: a separate line of work that lets you change code without touching the stable version.
  • Base branch: the branch you want your changes merged into, often called main.
  • Compare branch: the branch that contains your changes, often called a feature branch.

One point trips up beginners. A pull request is not a Git command. Git itself has commands such as commit, push and merge. The pull request is a feature added by hosting platforms on top of Git, and it is different from the git pull command, which downloads and merges remote changes into your local branch. If you are new to working this way, our guide to collaborative development explains why teams structure their work around shared review.

Why Pull Requests Matter

Pull requests exist because shared code is fragile. One careless change on a main branch can break the work of everyone who depends on it. A pull request adds a pause between writing code and shipping it, and that pause delivers several benefits.

  • Better code quality. A second pair of eyes catches logic errors, missing edge cases and unclear code before users ever see them.
  • Shared knowledge. Reviewers learn how other parts of the project work, and authors learn from feedback. Over time this spreads understanding across the team.
  • A permanent record. The title, description and discussion explain not just what changed but why. Months later, that context helps anyone puzzled by a decision.
  • A gate for automation. Tests, linters and security scans can run on every pull request, so problems are caught before the merge.
  • Safer releases. Work happens on isolated branches, so unfinished changes never leak into the stable version.

The security benefit deserves a note. Review and automated scanning at the pull request stage are one layer of defense, and they work best alongside broader security practices that protect your business beyond the codebase.

Anatomy of a Pull Request

Every pull request, on any platform, is built from the same handful of parts. Knowing them helps you write better PRs and review other people’s work faster.

ComponentPurposeWhat good looks like
TitleOne line summary shown in lists and notificationsSpecific, such as “Fix login button alignment on mobile”
DescriptionExplains what changed and whyContext, approach, links to the related issue, notes for reviewers
Base branchWhere the changes will be mergedUsually main or a release branch
Compare branchThe branch holding your changesA descriptive name such as feature/user-profile-update
CommitsThe individual saved steps of your workSmall, logical commits with clear messages
Files changed (diff)A line by line view of additions, deletions and editsFocused on one purpose
ReviewersPeople asked to examine the changeSomeone who knows the affected area
Labels and linked issuesHelp organize and track the workConsistent labels and a linked ticket
Status checksAutomated tests and scansAll passing before merge
ConversationComments, questions and decisionsResolved threads and clear approvals

What Is a Draft Pull Request?

A draft pull request is a work in progress that you have shared on purpose. It tells the team you are not asking for a formal review yet, but you want early feedback or want the automated checks to run. Use a draft when you are unsure about an approach, when a change is large and you want direction before going further, or when you simply want to show progress. When the work is ready, you mark it as ready for review and your reviewers are notified.

How a Pull Request Works, Step by Step

The pull request lifecycle follows the same rhythm on almost every team. Here is the full path from idea to merged code.

  1. Create a feature branch. Never work directly on the main branch. Make a new one for each change:

bash

   git checkout -b feature/user-profile-update
  1. Make your changes and commit. Save work in small, logical steps with clear messages:

bash

   git add .
   git commit -m "Add avatar upload to user profile"
  1. Push the branch to the remote repository. This makes your work visible to the team:

bash

   git push -u origin feature/user-profile-update
  1. Open the pull request. On the hosting platform, choose the base branch and the compare branch, then write a title and a description.
  2. Automated checks run. Tests, linters and security scans start as soon as the pull request opens.
  3. Reviewers respond. They comment, ask questions, approve, or request changes.
  4. Update the pull request. If changes are requested, commit and push to the same branch. The pull request updates automatically.
  5. Merge and clean up. Once the required approvals are in and checks pass, a maintainer merges the change. The feature branch is then usually deleted to keep the repository tidy.

Common pull request workflows

Teams organize branches in a few well known ways, and the pull request fits into each.

  • Feature branch workflow. Each change gets its own branch, and every branch is merged through a pull request. It is simple and suits most small and mid-sized teams.
  • Forking workflow. Common in open source. Contributors copy the whole repository into their own account, make changes there, and open a pull request back to the original project.
  • GitFlow. A more structured approach with long-lived branches such as main, develop, release and hotfix. Pull requests move changes between these branches, which suits larger teams with formal release cycles.

How to Create a Pull Request on GitHub

GitHub is where most people meet pull requests first. Once your branch is pushed, the process takes a few clicks. <!– Screenshot: GitHub repository page showing the Compare & pull request banner after a push. Take a fresh screenshot and add descriptive alt text. –>

  1. Open your repository on GitHub. After a recent push, a banner usually appears with a Compare & pull request button. Click it.
  2. If you do not see the banner, open the Pull requests tab and select New pull request.
  3. Choose the base branch (where changes will go) and the compare branch (your work).
  4. Write a clear title and a description explaining what changed and why. Link the related issue if there is one.
  5. Add reviewers, labels or assignees on the right side if your team uses them.
  6. Select Create pull request, or choose the draft option if the work is not ready for formal review.

If you contribute to a project you do not have write access to, fork the repository first, push your branch to your fork, and open the pull request from the fork to the original repository. If you are new to downloading and running projects from GitHub, our walkthrough on cloning and setting up a GitHub project covers the preparation steps.

You can also create a pull request from the terminal with the GitHub CLI by running gh pr create from your pushed branch. It prompts for a title and description. Check the current GitHub CLI documentation for available options, since flags can change between versions.

How Pull Request Review Works

Review is where a pull request earns its value. A reviewer reads the diff, runs the code if needed, and leaves feedback. The platform then records one of three outcomes:

  • Approve: the reviewer is satisfied and the change can move forward.
  • Comment: the reviewer shares thoughts or questions without a decision.
  • Request changes: the reviewer wants specific problems fixed before approval.

A practical reviewer checklist

When you review, work through questions like these:

  • Does the change solve the problem described in the pull request?
  • Are there tests, and do they pass?
  • Is the code readable, and will it be maintainable in a year?
  • Does it introduce a security risk, such as unvalidated input or exposed secrets?
  • Does the scope match the description, or has unrelated work slipped in?
  • Are there obvious performance concerns?
  • Are documentation and comments updated where needed?

Review etiquette

Good reviews are kind and specific. Critique the code, not the person. Ask questions instead of assuming intent, and suggest alternatives rather than only pointing out problems. As an author, respond to every comment, push fixes promptly, and treat feedback as a way to improve the result rather than a judgment. Agree on a reasonable turnaround time as a team, because a pull request that sits for days blocks everyone downstream.

Merging a Pull Request: Merge Commit, Squash and Rebase

When a pull request is approved, the platform usually offers more than one way to merge it. The choice affects how your project history looks, so teams pick one deliberately.

OptionWhat happensBest whenTrade-off
Merge commitKeeps every commit from the branch and adds a merge commit joining the historiesYou want a complete record of how the work evolvedHistory can become busy with merge commits
Squash and mergeCombines all the branch commits into a single commit on the base branchThe branch has many small or messy commitsYou lose the detailed step by step history on the base branch
Rebase and mergeReplays the branch commits onto the base branch without a merge commitYou prefer a clean, linear historyRewrites commit identifiers, which needs care on shared branches

Exact button names and behavior can vary by platform and settings, so confirm them in the official GitHub documentation for your setup. Many teams restrict which options are allowed so that history stays consistent.

How to Handle Merge Conflicts in a Pull Request

A merge conflict happens when two branches change the same lines and Git cannot decide which version to keep. It is a normal part of team work, not a mistake.

To fix one, update your branch with the latest changes from the base branch, open the files Git flags, and look for the conflict markers that show both versions:

text

<<<<<<< HEAD
your version of the lines
=======
the other version of the lines
>>>>>>> main

Edit the file so it contains the correct final result and remove the markers. Then commit the fix and push. The pull request updates, and the conflict warning clears. Smaller, shorter-lived branches conflict far less often, which is one more reason to keep pull requests focused.

Pull Request vs Merge Request (and Other Look-Alikes)

The same idea goes by different names depending on the platform.

TermWhere you see itNotes
Pull requestGitHub, BitbucketA request to pull your branch into another
Merge requestGitLabSame purpose, different name
DiffPhabricatorA similar reviewed unit of change

The purpose is identical everywhere: propose, review and merge a change. Differences lie in platform features such as approval rules and built-in pipelines, so check each platform’s documentation before assuming a feature exists.

Pull requests are also easy to confuse with nearby concepts:

  • Pull request vs git pull. The git pull command updates your local branch from a remote one. A pull request is a review request on a hosting platform.
  • Pull request vs commit. A commit is a saved snapshot of changes. A pull request bundles one or more commits for review.
  • Pull request vs branch. A branch is a line of development. A pull request is a proposal to merge that branch into another.
  • Pull request vs issue. An issue describes a problem or idea. A pull request contains the code that addresses it, and the two are often linked.

Pull Request Best Practices

Teams that enjoy their review process tend to follow the same habits.

  • Keep pull requests small and focused. One purpose per pull request is easier to review, faster to approve and less likely to hide a bug.
  • Write a descriptive title. “Fix login button alignment on mobile” beats “Bug fix” every time.
  • Explain what and why in the description. Include context, your approach, and anything reviewers should check closely.
  • Link the related issue or ticket. It gives reviewers the full backstory.
  • Review your own work first. Read your diff as if you were the reviewer. You will catch simple mistakes before anyone else sees them.
  • Run tests and linters locally. Do not spend a reviewer’s time on problems a tool can find.
  • Add screenshots for visual changes. A before and after image saves a lot of explanation.
  • Use draft pull requests for early feedback. Share direction before you invest in the wrong approach.
  • Protect important branches. Require approvals and passing status checks before anything can merge into main.
  • Delete the branch after merging. It keeps the repository clear about what is finished.

A pull request template you can copy

A template turns good habits into defaults. Save a version of this in your repository so every new pull request starts with the right prompts:

markdown

## Summary
What does this pull request change?

## Why
What problem does it solve? Link the issue: #

## How to test
Steps a reviewer can follow to verify the change.

## Screenshots
Add before and after images for visual changes.

## Checklist
- [ ] Tests added or updated
- [ ] Tests pass locally
- [ ] Documentation updated if needed
- [ ] No unrelated changes included

Teams that want help setting up review workflows, branching rules and release processes can bring in software development consulting to design a process that fits their size and tools.

Common Pull Request Mistakes to Avoid

Even experienced developers repeat a few avoidable errors.

  • Oversized pull requests. Hundreds of changed files across many topics are nearly impossible to review well. Split the work.
  • Empty or vague descriptions. Reviewers cannot judge a change they do not understand. Always explain the why.
  • Mixing unrelated changes. A bug fix, a refactor and a new feature belong in separate pull requests.
  • Force pushing over reviewed commits. It can erase the context of earlier review comments. Add new commits instead.
  • Merging with failing checks. A red check is a warning. Fix it or understand it before merging.
  • Letting pull requests sit. Stale pull requests drift out of date and create conflicts. Review promptly.
  • Leaving merged branches around. Delete them so the repository stays navigable.

Pull Requests in the Age of AI Coding Agents

Pull requests are taking on a new role. AI coding assistants and agents can now write changes and open pull requests on a person’s behalf, which makes the pull request the natural checkpoint where a human decides whether the work is ready. If you are exploring how such systems are designed, our article on building agentic AI applications covers the thinking behind them.

When a pull request is authored or assisted by AI, review it with the same care as any other, and pay extra attention to these points:

  • Tests: do they actually exercise the behavior, or do they only confirm what the code already does?
  • Hidden assumptions: has the code assumed something about data or users that is not true in your system?
  • Dependencies: were new packages added, and are they trustworthy and necessary?
  • Security: are inputs validated and secrets kept out of the code?
  • Scope: did the change stay within the requested task?

Automated and AI-assisted review tools can act as a useful first pass by flagging style problems, likely bugs or missing tests. They work best as a complement to human review, not a replacement for it, because a person still owns the decision to merge.

Pull Requests for WordPress and Website Teams

Pull requests are not only for software companies. Web agencies and in-house website teams keep theme and plugin code in Git repositories too, and the same review habits protect live sites from broken updates.

A sensible workflow for a website team looks like this: make changes on a feature branch, deploy the branch to a staging site, review the result together, and merge to production only after approval. This is especially valuable for custom WordPress plugin development, where one unreviewed change can affect checkout, forms or performance on a live site.

Agencies, freelancers and in-house marketing and development teams all benefit, because the pull request gives clients and stakeholders a clear record of what changed and who approved it. If you want a team to build and maintain code this way, our WordPress development services in Orange County are set up around reviewed, staged releases.

Frequently Asked Questions

What does PR stand for in programming?

PR stands for pull request. It is a request to merge code changes from one branch into another, usually from a feature branch into the main branch. The name comes from asking a project maintainer to pull your changes into their branch after the team has had a chance to review them.

Is a pull request the same as a merge request?

Yes, in practice. GitHub and Bitbucket call it a pull request, while GitLab calls it a merge request. Both are a formal proposal to merge one branch into another with review, discussion and automated checks. The workflow is the same; only the name and some platform features differ.

Do I need to be a developer to use pull requests?

No. Anyone who works in a Git repository can use them, including technical writers, designers who edit code or content files, and website teams maintaining themes and plugins. You need basic familiarity with branches and commits, but the review and discussion features are simple enough for non-developers to follow.

Can I change a pull request after opening it?

Yes. Push new commits to the same branch and the pull request updates automatically, so reviewers see your latest changes. You can also edit the title and description at any time. Avoid force pushing over commits that have already been reviewed, because it can make earlier review comments hard to follow.

What is a draft pull request?

A draft pull request signals that your work is not ready to merge but you want early feedback or want automated checks to run. Reviewers can look at it without being asked for a formal approval. When you are ready, you mark it as ready for review and the normal review process begins.

Who merges a pull request?

Usually a repository maintainer or the author, depending on team rules. Many teams require one or more approvals and passing status checks before anyone can merge. On protected branches, the platform enforces these rules, so a pull request cannot be merged until the required conditions are met.

Can a closed pull request be reopened?

Often yes. If a pull request was closed without being merged, you can usually reopen it from the pull request page, provided the branch still exists and the project permissions allow it. If the branch was deleted, restore it or open a new pull request from the same commits.

Conclusion

A pull request is a request to merge a branch into another after the change has been seen, discussed and tested. It protects the main codebase, spreads knowledge across a team and leaves a record of why code changed. Keep your pull requests small, describe them well, review them kindly, and let automated checks handle what tools can handle.

If your team is setting up its first review workflow or wants an expert to tighten an existing one, book a technical consultation and we will help you build a process that works.