Appearance
13.11.8 — Working on a Team: Pull Requests, Reviews and Branching Strategy
On your own, Git is a tool for saving and undoing. On a team of ten, it becomes the way you all avoid stepping on each other.
Ten people push to the same project every day. Someone has to decide what is allowed into the main line. Someone has to look at a change before it goes live. And when a bug appears at 3 am, someone has to be able to read the history and find out why a line exists.
This page shows how teams do it: the pull request, the review, the rules that protect main, how open-source contributors work without any access, and the habits that make a history readable.
1. What a pull request is
First, a fact that surprises people: a pull request is not a Git feature. Git itself has no such thing. It is a feature of hosting sites such as GitHub, GitLab and Bitbucket. (GitLab calls it a merge request, which is the same idea with a different name.)
A pull request (PR) is a web page that says: "I have work on branch feature/coupons. Please merge it into main." The page shows:
- A title and description that explain the change.
- The diff: every line that changed, file by file.
- A conversation: comments on individual lines, and on the PR as a whole.
- Checks: automatic jobs (build, lint, and so on) that run on your branch, each with a green tick or a red cross. Chapter 13.7 explains continuous integration.
- Reviewers, and whether they have approved.
- A merge button, which stays disabled until the rules are satisfied.
The purpose is a conversation before the change lands. It is a chance for a teammate to catch a bug, suggest a clearer name, or ask "why are we doing this?". It is also how knowledge spreads: reviewing is how people learn each other's code.
2. The everyday cycle (GitHub flow)
Most teams follow the same loop for every task. It is called GitHub flow.
main without a pull request that others have looked at and the automatic checks have passed.Here are the steps as commands. We build the coupon feature from Chapter 13.11.3.
Step 1: start from the latest main, and make a branch.
bash
git switch main
git pull
git switch -c feature/couponsNever start from an old main. The pull makes sure your branch begins where the team is now, which means fewer conflicts later.
Step 2: work and commit. Small, clear commits (section 9 below).
bash
git add -p
git commit -m "Validate coupon codes"Step 3: push the branch.
text
$ git push -u origin feature/coupons
To github.com:acme/shop.git
* [new branch] feature/coupons -> feature/coupons
remote: Create a pull request for 'feature/coupons' on GitHub by visiting:
remote: https://github.com/acme/shop/pull/new/feature/couponsGitHub prints a link to open the pull request. (If you use GitHub's command line tool, gh pr create does the same.)
Step 4: open the pull request. Write a title and a description (section 3).
Step 5: respond to review. Teammates comment. You fix things by making more commits on the same branch and pushing. The pull request updates itself, and the checks run again.
bash
git add -p
git commit -m "Reject expired coupons"
git pushStep 6: merge, then clean up. When the checks are green and a teammate approves, someone presses the merge button. Then update your laptop and delete the finished branch:
bash
git switch main
git pull
git branch -d feature/couponsAnd you start again. A branch lives for one task, then it is gone.
Keeping your branch current
If main moves while you work, your pull request may start to conflict. Bring main in:
bash
git fetch origin
git rebase origin/main # or: git merge origin/main
git push --force-with-lease # only needed after a rebaseChapter 13.11.6 explains the two choices. If others review your branch, merging main in is gentler, because it adds commits instead of rewriting them.
3. Writing a pull request that gets reviewed
A pull request is a message to a busy person. Make it easy to say yes.
Keep it small. A change of 100 lines gets read carefully. A change of 2,000 lines gets a quick "looks fine" and a hidden bug. If a task is big, split it into steps that each make sense on their own.
One purpose per pull request. Do not fix a bug, rename variables and upgrade a library in the same one. Each reason deserves its own review and its own revert.
Write a description that answers the reviewer's questions:
text
Title: Reject refunds outside the 30-day window
What
The refund endpoint now checks the order date.
Why
Support could refund year-old orders by pasting an old link (#482).
How I checked it
Refunded a fresh order (works) and a 45-day-old order (rejected).
Notes for the reviewer
The window is a constant in refund.ts. We may want it configurable later.Four short headings: what, why, how you checked it, and anything to look at carefully. Add screenshots for visual changes. Teams save the structure in a file named .github/pull_request_template.md, and GitHub fills it into every new pull request.
Link the issue. Writing Fixes #482 in the description (or in a commit message) closes that issue automatically when the change is merged into the main branch.
Use a draft. If you want early feedback on unfinished work, open a draft pull request. It cannot be merged, and it tells reviewers "do not judge yet".
Read your own diff first. Before you ask anyone else, open the PR and read the changes yourself. You will find stray debug lines and forgotten files about half the time.
4. Reviewing someone else's pull request
Reviewing is a skill. A good review does not look for mistakes in the author. It looks for problems in the change.
What to look for, in rough order of importance:
- Does it do what the description says? Does it solve the real problem?
- Is it correct? Edge cases, error handling, what happens with empty or very large input.
- Is it safe? Secrets, permissions, user input going straight into a query (Chapter 8.5.1).
- Can you understand it? Names, structure, comments that explain why.
- Style and small things last, and ideally automated by a formatter so no human argues about them.
Three habits make reviews pleasant:
- Ask questions instead of giving orders. "What happens if the coupon is empty?" teaches more than "Wrong."
- Mark small remarks as optional. Many teams write
nit:("nitpick") before trivial suggestions, so the author knows they may ignore them. - Say what is good. One kind sentence costs nothing and changes the mood of the whole thread.
When you finish, you choose one of three: comment (just remarks), approve, or request changes (the author must respond before merging).
5. The three merge buttons
When a pull request is ready, GitHub offers three ways to merge it. They are exactly the options from Chapter 13.11.6:
| Button | What lands on main | Pick it when |
|---|---|---|
| Create a merge commit | All the branch's commits, plus a merge commit | You want the full history and branch shape |
| Squash and merge | One single commit with the whole change | Branches are short, one PR is one change |
| Rebase and merge | The branch's commits, replayed in a straight line | Your commits are already clean and you want them kept |
A team usually picks one and sets it as the only allowed option, so the history stays consistent. Squash and merge is the most common choice. After merging, tick Delete branch so stale branches do not pile up.
6. Protecting main
On a team, you do not want anyone, even a senior engineer in a hurry, to push straight to main. The hosting site lets you set branch protection rules, which Git itself cannot enforce:
- Require a pull request before merging. Nobody pushes to
maindirectly. - Require approvals (one or two reviewers).
- Require status checks to pass, for example the build and the linter.
- Require the branch to be up to date with
mainbefore merging. - Block force pushes and deletion of
main. This protects the history from the dangerous commands in Chapter 13.11.4.
CODEOWNERS adds one more idea: some code needs a particular reviewer. A file named .github/CODEOWNERS maps paths to people or teams:
text
# Anyone touching payments code needs the payments team to approve
/src/payments/ @acme/payments-team
*.sql @acme/database-teamGitHub then asks the right people automatically, and can refuse to merge until they approve.
You can also require signed commits. A signature (made with a GPG or SSH key) proves a commit really came from the person named in it, because the author name in Git is only text anyone can type. GitHub shows a "Verified" badge. Chapter 8.2 explains signatures.
These rules are the server-side enforcement from Chapter 13.11.5: a local hook is a suggestion, and a protected branch is a rule.
7. Contributing to a project you do not own: forks
You find a bug in an open-source library and want to fix it. You cannot push to their repository, because you are not a member. Instead you use a fork.
upstream, to stay in step with the original.A fork is your own copy of their repository, on GitHub. You push freely to it. Then you ask the owners to take your change with a pull request that goes from your fork to their repository.
bash
# 1. Click "Fork" on GitHub. Then clone YOUR fork:
git clone git@github.com:ana/their-library.git
cd their-library
# 2. Add the original as a second remote, called upstream:
git remote add upstream git@github.com:theirs/their-library.git
git remote -v
# origin git@github.com:ana/their-library.git (fetch) <- your fork
# upstream git@github.com:theirs/their-library.git (fetch) <- the original
# 3. Work on a branch, push it to YOUR fork, open a pull request on GitHub:
git switch -c fix/empty-input
git commit -am "Handle empty input"
git push -u origin fix/empty-inputOver time the original moves on. To stay in step, fetch from upstream:
bash
git fetch upstream
git switch main
git rebase upstream/main # or merge
git push origin main # update your fork's mainThe names are conventions: origin is where you push, upstream is the project you follow. Inside a company, people usually skip forks and push branches straight to one shared repository. Forks matter for open source, where strangers cannot be given write access.
8. How teams organise their branches
Teams also need a rule for how branches are used. There are three common ones.
Trunk-based development. There is one main line (the trunk). Everyone works on very short branches, a day or two at most, and merges back often. Unfinished work is hidden behind a feature flag: a setting that keeps new code switched off in production until it is ready, so unfinished code can still be merged safely. It is the best fit for software that is deployed continuously, and it is the default recommendation in Chapter 13.7.
GitHub flow is the loop from section 2: a short branch per task, a pull request, a merge. It is trunk-based development with a review step. It is what most teams actually run.
GitFlow uses several long-lived branches: develop for the next release, release/* for preparing one, hotfix/* for emergency fixes, and main for released code. It was designed for software with numbered versions and scheduled releases, such as a mobile app or a product installed by customers. For a website that deploys many times a day it is a poor fit, because long-lived branches mean big, risky merges.
How to choose? Ask: how often do we ship? Shipping daily points to trunk-based or GitHub flow. Shipping a numbered version every few months, and supporting old versions, points to GitFlow. When unsure, start simple.
9. Writing history that others can read
Every commit you make will be read by someone later: a teammate searching for why a line exists, or you, at 3 am, during an incident. git blame leads to a commit message. If it says "fix stuff", you hit a dead end. If it explains the situation, you have your answer.
Atomic commits. One logical change per commit. Not "morning's work", and never a commit that leaves the project unable to build. This is what makes review, revert and bisect all work (Chapter 13.11.7).
Messages that help. A short subject, a blank line, then the reason.
text
Reject refunds outside the 30-day window
The refund endpoint accepted any order id, so support could issue
refunds on year-old orders by pasting a stale link.
Fixes #482The rules of thumb that most teams follow:
- The subject is a command in the imperative: "Add", "Fix", "Reject", not "Added" or "Fixing". A good test: the subject should complete the sentence "If applied, this commit will…".
- Keep the subject under about 50 characters, so it fits on one line in
git log --oneline. - Leave one blank line, then explain why in lines of about 72 characters. The code already shows what. Only you can say why.
- Mention an issue number to link the commit to the discussion.
Conventional commits is a convention that adds a machine-readable prefix: feat: for a new feature, fix: for a bug fix, docs:, refactor:, perf:, chore:. A ! after the type, or a BREAKING CHANGE: footer, marks a change that breaks existing users.
text
feat(cart): apply coupon codes
fix(refund): reject orders older than 30 days
feat(api)!: remove the v1 endpointsTools can then work out the next version number and write the changelog from the commit messages. Adopt it if you want that automation. If your team adopts the format without the tooling, you pay the cost of the typing and get none of the benefit.
Tidy before you share. Use git rebase -i and --autosquash on your own branch (Chapter 13.11.6) to fold "fix typo" commits away before reviewers see them. Once reviewers have started reading, add commits instead of rewriting, so they can see what changed since their last look. If the team squashes on merge, the final history will be tidy anyway.
10. Habits that keep a team happy
- Pull before you start, and before you push. Most conflicts come from working on an old copy.
- Never commit to
maindirectly when it is protected. Even when it is not, do not. - Never force-push a shared branch. Your own branch, after a rebase, with
--force-with-lease, is the one exception (Chapter 13.11.3). - Keep generated files, secrets and large binaries out. Use
.gitignore(Chapter 13.11.1) and, for big files, Git LFS. - Do not leave branches rotting. Delete merged ones on the server and run
git fetch --prunelocally. - Share your hooks. Tools like Husky keep the pre-commit checks in the repository so everyone runs the same ones (Chapter 13.11.5).
- Communicate about risky operations. If you must rewrite a shared branch, say so first, in the channel, not after.
What the interviewer will push on
These questions check whether you can work with other people through Git, which is most of the job.
"What is a pull request?" A request, on a hosting site, to merge one branch into another, with a diff, a discussion and automatic checks. The tell: saying it is not part of Git itself. A strong answer then says why teams use it: review before merging, and checks that must pass.
"Walk me through how you would contribute a feature on a team." The full loop: update main, create a branch, small commits, push, open a PR, respond to review with more commits, merge, delete the branch. Mentioning that the branch is short-lived and the PR is small shows you have done this for real.
"What is the difference between merge, squash and rebase when merging a PR?" Merge keeps every commit and adds a merge commit. Squash makes one commit. Rebase puts the commits in a line without a merge commit. Say which your team picks and why.
"How do you stop people pushing broken code to main?" Branch protection: require pull requests, approvals and passing checks, block force-push. Point out that a local hook can be bypassed, but server rules cannot.
"What is a fork, and how is it different from a branch?" A fork is a whole copy of a repository under your own account. A branch is a label inside one repository. You fork when you cannot push to the original.
"Trunk-based development or GitFlow?" Answer with a criterion, not a preference: how often do you ship? Continuous deployment favours short branches and feature flags. Versioned releases supported for months favour GitFlow. The wrong answer is the one that says either is "best".
"What makes a good commit message?" Imperative subject under about 50 characters, a blank line, a body that explains why, and an issue reference. Add that you write history for the person debugging at 3 am.
One thing to volunteer: say that you read your own diff before requesting review, and keep pull requests small. It signals that you respect reviewers' time, which is what senior engineers notice.
Recall
- A pull request is a feature of the hosting site, not of Git: a page with a diff, discussion, automatic checks and a merge button. Its value is review before the change lands.
- GitHub flow:
switch main,pull,switch -c feature/x, small commits,push -u, open a PR, answer review with more commits on the same branch, merge, delete the branch. - A good PR is small and has one purpose, with a description covering what, why, how you checked, and where to look.
Fixes #482closes the issue on merge. Use draft PRs for early feedback, and read your own diff first. - Review the change, not the author: correctness and safety before style; ask questions; mark small remarks
nit:. - Merge buttons: merge commit (full history), squash and merge (one commit), rebase and merge (straight line). Pick one for the whole team and delete the branch after.
- Protect
main: require PRs, approvals and passing checks; block force-push and deletion. CODEOWNERS routes reviews by path. Signed commits prove authorship. Server rules enforce; local hooks only suggest. - Forks: your own copy of someone else's repository. You push to
origin(your fork), followupstream(the original), and open a PR from fork to original. - Branching strategies: trunk-based (very short branches, feature flags, continuous deployment), GitHub flow (branch per task, PR), GitFlow (long-lived
develop/release/hotfix, for versioned releases). Choose by how often you ship. - Commit hygiene: atomic commits; imperative subject under about 50 characters, blank line, then why; conventional commits only if you use the tooling; rewrite your own branch before review, add commits after.
Self-test: Why is a pull request not part of Git? · What goes in a good PR description? · What rules would you put on main, and why can a hook not replace them? · What is upstream, and when do you need it? · Trunk-based or GitFlow, and what decides it? · What are the parts of a good commit message?
Next: Chapter 15.2 widens the view from Git to the rest of the engineer's toolbox: how command-line tools work inside, diagrams as code, and the automation that removes the jobs nobody should do by hand.