What a pull request is
A pull request is a proposal to merge your branch into another branch. It has a page where other people can read the change, discuss it and approve it. Teams use it to catch mistakes before they reach the main line.
A new price list is about to go live. A colleague reads the change first and spots a price with a misplaced decimal point.
By the end of this lesson
Note
I can propose a change and review one.
Key words
| Word | What it means |
|---|---|
| Pull request | a request to merge a branch, with a page to discuss it |
| Review | reading a change to decide if it is ready |
| Diff | the lines a change adds and removes |
| Reviewer | the person who reads and judges the change |
| Approve | to say a change is ready to merge |
The cells students fill in are left blank in this preview.
A pull request asks for a merge
You do your work on a branch and push the branch to the server. Then you open a pull request. It says: please merge this branch into main.
The page shows the diff, which is every line the branch adds and removes. Other people comment on lines, ask for changes and finally approve. Only then does someone press Merge.
Gitea draws the pull request page
A pull request is a feature of the server, not of Git itself. Git has only branches and merges. Gitea adds the page, the comments and the Merge button.
In the lab's Gitea you can try one after the lab task. Push a branch, open the repository page, press New Pull Request, choose your branch, write a title and press Create. Git does the merge when you press the button.
A reviewer reads the diff, not everything
You can make the same view in the terminal. First make a small repository called review with three prices. Then make a branch that lowers the price of tea.
Your name and address are set from lesson 1. If the lab was restarted, set them again.
Make a repository called review
git init -b main reviewShown here, not run. Create a free account to press Run and type it into your own lab’s terminal.
Make a file with three prices
printf 'Latte 3.20\nTea 2.10\nCake 3.50\n' > review/prices.txtShown here, not run. Create a free account to press Run and type it into your own lab’s terminal.
Stage the file
git -C review add prices.txtShown here, not run. Create a free account to press Run and type it into your own lab’s terminal.
Save the first commit
git -C review commit -m "Add prices"Shown here, not run. Create a free account to press Run and type it into your own lab’s terminal.
Make a branch for the change
git -C review switch -c cheaper-teaShown here, not run. Create a free account to press Run and type it into your own lab’s terminal.
Lower the price of tea
sed -i 's/Tea 2.10/Tea 2.00/' review/prices.txtShown here, not run. Create a free account to press Run and type it into your own lab’s terminal.
Commit the change
git -C review commit -am "Lower the price of tea"Shown here, not run. Create a free account to press Run and type it into your own lab’s terminal.
See the size of the change
git -C review --no-pager diff --stat main cheaper-teaShown here, not run. Create a free account to press Run and type it into your own lab’s terminal.
See the changed lines
git -C review --no-pager diff -U0 main cheaper-teaShown here, not run. Create a free account to press Run and type it into your own lab’s terminal.
A good review checks the same things
A reviewer does not need to be clever. They check the same short list on every change. A small change is easy to check, and a huge one is not.
Worked example: a review checklist
| Question | Why it matters |
|---|---|
| Is the change small? | People read ten lines carefully and a thousand lines badly |
| Does it do one thing? | A mixed change is hard to undo when one part is wrong |
| Does the title say what it does? | The history is read for years |
| Does it add a secret or a TODO? | A password in the history stays there for ever |
The cells students fill in are left blank in this preview.
A common mistake
Warning
Many people think a review is there to find a person's faults. It is not. A review checks the change, not the writer. Say what you see and ask a question, such as "Is 2.00 meant to be 20.0?", and approve when the change is ready.
Go back to main
git -C review switch mainShown here, not run. Create a free account to press Run and type it into your own lab’s terminal.
Merge with a merge commit
git -C review merge --no-ff -m "Merge cheaper-tea" cheaper-teaShown here, not run. Create a free account to press Run and type it into your own lab’s terminal.
Draw the history as a graph
git -C review --no-pager log --graph --format=%sShown here, not run. Create a free account to press Run and type it into your own lab’s terminal.