Pull Requests
A Pull Request (PR) is a formal proposal to merge the commits on one branch into another. It’s where code review happens, where automated checks run, and where decisions about a change get recorded for posterity. PRs are a feature of the hosting platform — GitHub, GitLab, Bitbucket — not of Git itself; Git only knows about commits and branches.
PRs vs MRs
GitHub and Bitbucket call them Pull Requests. GitLab and some self-hosted tools call them Merge Requests (MRs). They’re the same idea with different branding. The lifecycle, the review tools, and the underlying Git operations are identical.
The four pieces of a PR
Base branch — where the changes will land (often
mainordevelop).Compare branch — the branch containing your new commits.
Title and description — what the change does and why.
Diff — the file-by-file delta between base and compare.
PR anatomy on GitHub
Open any PR and you’ll see six tabs / sections:
Conversation — description, review comments, status checks, merge button.
Commits — the list of commits being proposed.
Checks — CI/CD pipelines, linters, deploy previews.
Files changed — the diff, with inline review controls.
Reviewers / Assignees / Labels — sidebar metadata.
Linked issues — issues this PR will close on merge.
The full lifecycle
PR lifecycle
local branch → push to remote → open PR → CI runs
│
reviewers comment / request changes
│
push fixes, re-request review
│
approved
│
merge (squash/rebase/merge)
│
delete branch, close PRDraft PRs
Open a PR as a Draft when you want CI to run and want early eyeballs but aren’t ready for formal review. Drafts can’t be merged until you click Ready for review. They’re the polite version of “please don’t merge this yet.”
Open a draft from the CLI
gh pr create --draft --title "WIP: new search index" --body "Sketching the API"
Linking PRs to issues
Put a closing keyword in the PR description and GitHub will close the linked issue automatically when the PR merges.
In the PR description
## Summary Adds the user avatar component. Fixes #142 Closes #150 Resolves acme-co/design-system#88
Fixes #N,Closes #N,Resolves #N— any of these work.Issue closes when the PR merges into the default branch.
Use
org/repo#Nto link an issue in a different repo.
Reviewers and review states
A reviewer can leave a review in one of three states:
State | Meaning | Blocks merge? |
|---|---|---|
Comment | Feedback without a verdict | No |
Approve | Looks good to me, merge when ready | No (it unblocks) |
Request changes | Don’t merge until I see updates | Yes (when branch protection is on) |
Merge methods compared
GitHub offers three ways to land a PR. Each has trade-offs; teams pick one as a convention.
Method | History shape | Commits in main | Best for |
|---|---|---|---|
Merge commit | Branch joined back with a merge commit | All PR commits + 1 merge commit | Preserving exact branch history |
Squash and merge | Linear, one commit per PR | 1 commit (squashed) | Clean main, treating PR as the unit of change |
Rebase and merge | Linear, PR commits replayed | All PR commits, no merge commit | Linear history + commit-level granularity |
Branch protection
Repos can require: a minimum number of approvals, passing CI, up-to-date branches, signed commits, and resolved conversations before the Merge button activates. Branch protection is what turns PRs from a polite request into an enforced gate.
Closing a PR without merging
Click Close pull request at the bottom of the conversation. The commits stay on the branch; you just decide not to land them. Closed PRs can be reopened later if you change your mind.
Real-world workflow
From idea to merged PR
# 1. Branch git switch -c add-search-filter # 2. Commit git commit -am "Add search filter component" # 3. Push git push -u origin add-search-filter # 4. Open PR (in browser or CLI) gh pr create --fill # 5. Address review feedback git commit -am "Fix lint, add tests" git push # 6. Merge in browser → branch auto-deletes