What is a pull request?
So far you have merged branches on your computer, by yourself. When people work together, they
want to see a change before it goes into main: to check it, comment on it, and agree. GitHub’s
tool for this is the pull request: a page that says “please merge my branch into main”,
shows exactly what would change, and has a place to discuss it. When everyone is happy, a click
merges it. The name means “please pull my branch into yours”. It is not the git pull command:
you create a pull request on GitHub’s website.
Pull requests are how almost every team on GitHub works, and how you suggest changes to someone else’s project. Using them for your own project is good practice too, so you will do that now.
The pull request flow. Make a branch and commit to it, push the branch to GitHub, open a pull
request, review it, merge it on GitHub, then pull main and delete the branch on your computer.
Make a branch with a change
Open my-page in VS Code with a terminal, and check that you are in my-page, not in
my-page-laptop:
$ pwd/Users/you/my-pageThen start with the daily routine from Lesson 9: get the latest work first.
$ git pullAlready up to date.Now a branch for a new section of your page:
$ git switch -c add-contactSwitched to a new branch 'add-contact'Add the two highlighted lines at the end of the page, before </body>:
<!DOCTYPE html><html lang="en"><head> <meta charset="utf-8"> <title>About me</title> <link rel="stylesheet" href="style.css"></head><body> <h1>Welcome to my page!</h1> <p>This is my first web page, published with GitHub Pages.</p> <p>I like walking, photography and good coffee.</p> <h2>My hobbies</h2> <ul> <li>Walking</li> <li>Photography</li> <li>Cooking</li> </ul> <h2>Contact</h2> <p>You can find me on GitHub as your-username.</p></body></html>$ git add index.html$ git commit -m "Add a contact section"[add-contact 904037b] Add a contact section
1 file changed, 2 insertions(+)Push the branch
Send the branch to GitHub. GitHub has no add-contact yet, so a plain git push would not know
where to send it. As with main in Lesson 7, use -u the first time: -u origin add-contact
creates the branch on GitHub and pairs the two.
$ git push -u origin add-contactEnumerating objects: 5, done.
Counting objects: 100% (5/5), done.
Delta compression using up to 8 threads
Compressing objects: 100% (3/3), done.
Writing objects: 100% (3/3), 450 bytes | 450.00 KiB/s, done.
Total 3 (delta 1), reused 0 (delta 0), pack-reused 0 (from 0)
remote: Resolving deltas: 100% (1/1), completed with 1 local object.
remote:
remote: Create a pull request for 'add-contact' on GitHub by visiting:
remote: https://github.com/your-username/my-page/pull/new/add-contact
remote:
To https://github.com/your-username/my-page.git
* [new branch] add-contact -> add-contact
branch 'add-contact' set up to track 'origin/add-contact'.The lines starting with remote: come from GitHub itself. It noticed a new branch and suggests a
pull request, with a link. You can Ctrl+click the link (Cmd+click on a Mac)
to open it, or go to the repository page as below.
If something went wrong
fatal: The current branch add-contact has no upstream branch. You typed git push on its
own. Run git push -u origin add-contact. (Git’s own suggestion, --set-upstream, means the
same as -u.)
Open the pull request
- Go to your repository’s page. A yellow banner says that
add-contacthad recent pushes. Click Compare & pull request. - The page shows base
mainand compareadd-contact: you ask to mergeadd-contactintomain. Below it are the commit and the changes. - The title box shows your commit message, “Add a contact section”; if it does not, type it. In the description box, write a sentence about the change, for example: “Adds a short contact section at the end of the page.”
- Click Create pull request.
Your pull request has a number, #1, and its own page with tabs. Three of them matter here:
- Conversation: the description, comments, and the merge button at the bottom.
- Commits: the commits on the branch.
- Files changed: the diff, with added lines in green, as in
git diff.
(Checks shows automatic tests; your project has none.)
Review it
Click Files changed and read the change. This is what a reviewer does. On your own project there is nobody else to review it, so a careful read is enough.
(Optional) To comment on a line, hover over it and click the blue comment icon that appears, write your comment, and click Comment (in some views, Add single comment). Start a review is for collecting several comments before sending them.
The point of a review is to catch mistakes before they reach main, and on your project
main is your live web page. A second look is cheap; fixing a broken page is not.
If the review finds a problem, you do not need a new pull request. Fix it on your computer, on
the same branch, commit, and git push. The pull request updates itself with the new commit.
Merge it on GitHub
- Go back to the Conversation tab and scroll to the bottom.
- Click Merge pull request, then Confirm merge. The pull request is now “Merged”.
- Click Delete branch. The branch has done its job; the commits stay in
main.
GitHub merged add-contact into main with a merge commit, like the second merge in Lesson 5.
GitHub always makes one, so that the history records the pull request, even when, as here,
git merge on your computer would only have moved the label forward. Because main changed,
GitHub Pages republishes your site: in a minute or two the contact section is online.
Bring the merge home and tidy up
The merge happened on GitHub, so your computer does not have it yet. Switch to main and pull:
$ git switch mainSwitched to branch 'main'
Your branch is up to date with 'origin/main'.$ git pullremote: Enumerating objects: 1, done.
remote: Counting objects: 100% (1/1), done.
remote: Total 1 (delta 0), reused 1 (delta 0), pack-reused 0 (from 0)
Unpacking objects: 100% (1/1), 264 bytes | 264.00 KiB/s, done.
From https://github.com/your-username/my-page
22893c9..32cd9ea main -> origin/main
Updating 22893c9..32cd9ea
Fast-forward
index.html | 2 ++
1 file changed, 2 insertions(+)(“Up to date with ‘origin/main’” was the old note again, as in Lesson 9.) Your main had not
moved, so it only has to move forward to GitHub’s merge commit: that is why Git says
“Fast-forward”. Now delete the branch on your computer too:
$ git branch -d add-contactDeleted branch add-contact (was 904037b).Your computer still has a note of the branch on GitHub, origin/add-contact. git fetch is the
first half of git pull: it downloads news from GitHub and updates your notes, such as
origin/main, but does not change your files or your branches. --prune (as a gardener prunes
dead branches) also removes notes of branches that were deleted on GitHub. This is only tidying:
nothing breaks if you forget it.
$ git fetch --pruneFrom https://github.com/your-username/my-page
- [deleted] (none) -> origin/add-contactThe history shows the merge GitHub made:
$ git log --oneline --graph -3* 32cd9ea (HEAD -> main, origin/main, origin/HEAD) Merge pull request #1 from your-username/add-contact
|\
| * 904037b Add a contact section
|/
* 22893c9 Merge branch 'main' of https://github.com/your-username/my-page
|\That is the whole pull request routine: branch, commit, push, open, review, merge, pull, delete.
If something went wrong
There is no yellow banner. Click the Pull requests tab, then New pull request, and
choose add-contact as the compare branch.
The merge button is grey and says there are conflicts. main changed in the same lines since
you made the branch, usually on GitHub. On your computer, first get GitHub’s newest main:
git switch main, then git pull. Then git switch add-contact and git merge main, resolve the
conflict as in Lesson 6 (git add, git commit), and git push. The pull request updates, and
you can merge.
Working with other people
Everything you have done works the same when other people join in.
Invite a collaborator to your repository
- On your repository’s page, click Settings.
- In the sidebar, under “Access”, click Collaborators, then Add people. GitHub may first ask you to confirm your password: that is a normal safety check.
- Type the person’s GitHub username, choose them, and click the button to add them.
They get an email invitation. Once they accept, they can push to your repository. A good way to
work together: each of you works on your own branches, pushes them, and opens pull requests; the
other reviews and merges. Everyone pulls main before starting new work.
Suggest a change to someone else’s project
You cannot push to someone else’s project unless they make you a collaborator. Instead, you make your own copy of it on GitHub, called a fork, and send your change from there:
- On the project’s GitHub page, click Fork in the top-right corner, then Create fork. GitHub makes a copy under your account.
- Clone your fork, from your home folder (
cd ..out ofmy-pagefirst). To get its address, open the fork’s page, whose name starts with your username, click the green Code button and copy the address. Then make a branch, commit, and push it to your fork. - Go to the original project’s page. GitHub shows a yellow banner for your branch there too: click Compare & pull request, describe your change and create the pull request.
- The project’s owners review it. They may ask for changes (you push more commits to your branch) and, if they like it, merge it.
That is how millions of people contribute to open-source projects. To practise, github.com/firstcontributions/first-contributions is a project made for exactly this.
If something went wrong
Permission to OWNER/PROJECT.git denied to your-username, or The requested URL returned error: 403. You cloned the original project, not your fork. The address that git remote -v shows must
contain your username. Clone your fork, and make your change there.
What you learned
- A pull request asks to merge a branch, shows the changes, and is the place to review and discuss them.
- The routine: branch, commit, push the branch, open the pull request, review, merge on GitHub,
then pull
mainand delete the branch. - More commits pushed to the branch update an open pull request.
git fetch --pruneremoves notes of branches deleted on GitHub.- Collaborators can push to your repository; anyone else can fork it and send a pull request.
| Command | What it does |
|---|---|
git push -u origin BRANCH |
Sends a new branch to GitHub |
git switch main then git pull |
Brings a merged pull request to your computer |
git branch -d BRANCH |
Deletes the finished branch on your computer |
git fetch --prune |
Gets news from GitHub and drops notes of deleted branches |
Check yourself
git pull is a different thing.git pull on main on your computer?