297

How do I create and/or send a pull request to another repository hosted on GitHub?

tim peterson
  • 23,653
  • 59
  • 177
  • 299
  • 2
    Isn't this sufficiently explained in the [GitHub help pages](https://help.github.com/)? – lanzz Feb 04 '13 at 06:52
  • 27
    @lanzz No, the help page doesn't include a few useful tips, that I wish I knew before doing my first pull requests (see below). – VonC Feb 04 '13 at 07:08
  • 10
    @ianzz of course Github's page is "sufficient", but there are many ways to learn. What I strived to do was make a beginner-level tutorial. What I found lacking in Github's explanation was that: 1) it wasn't contained in one source (two pages which are not clearly linked), 2) was not succinct (those pages are very long, long=overwhelming), 3) was not explained in human terms in key sections. In teaching, it is always difficult for a more experienced teacher to know what a beginner doesn't know. Putting myself in the shoes of the beginner was my aim in writing this. – tim peterson Feb 04 '13 at 14:09
  • The advantage of long pages is that you _might_ end up understanding the process involved. The disadvantage of a "succinct" explanation is that you're much more likely to end up following steps blindly, without understanding what you're doing, and if something goes wrong you have no idea what and why happened. – lanzz Feb 05 '13 at 07:46
  • 12
    Long can mean overwhelming which can mean abort= **no** learning. One can "end up understanding the process involved" via many avenues that would obviously just not be one of them. To end the flame war, there is no need to reply, I understand where you're coming from. – tim peterson Feb 05 '13 at 14:34
  • 8
    You make a pull request from your own fork. That was *definitely not* my original assumption. – Derek Illchuk Apr 04 '15 at 23:04
  • [The Simplest GitHub Pull Request is from the web interface without using git](https://stackoverflow.com/a/61152349/4539999) – flywire Apr 11 '20 at 05:07

8 Answers8

244

(In addition to the official "GitHub Help 'Using pull requests' page",
see also "Forking vs. Branching in GitHub", "What is the difference between origin and upstream in GitHub")

Couple tips on pull-requests:

Assuming that you have first forked a repo, here is what you should do in that fork that you own:

  • create a branch: isolate your modifications in a branch. Don't create a pull request from master, where you could be tempted to accumulate and mix several modifications at once.
  • rebase that branch: even if you already did a pull request from that branch, rebasing it on top of origin/master (making sure your patch is still working) will update the pull request automagically (no need to click on anything)
  • update that branch: if your pull request is rejected, you simply can add new commits, and/or redo your history completely: it will activate your existing pull request again.
  • "focus" that branch: i.e., make its topic "tight", don't modify thousands of class and the all app, only add or fix a well-defined feature, keeping the changes small.
  • delete that branch: once accepted, you can safely delete that branch on your fork (and git remote prune origin). The GitHub GUI will propose for you to delete your branch in your pull-request page.

Note: to write the Pull-Request itself, see "How to write the perfect pull request" (January 2015, GitHub)

March 2016: New PR merge button option: see "Github squash commits from web interface on pull request after review comments?".

squash

The maintainer of the repo can choose to merge --squash those PR commits.

After a Pull Request

Regarding the last point, since April, 10th 2013, "Redesigned merge button", the branch is deleted for you:

new merge button

Deleting branches after you merge has also been simplified.
Instead of confirming the delete with an extra step, we immediately remove the branch when you delete it and provide a convenient link to restore the branch in the event you need it again.

That confirms the best practice of deleting the branch after merging a pull request.

pull-request vs. request-pull

e-notes for "reposotory" (sic)

<humour>

That (pull request) isn't even defined properly by GitHub!

Fortunately, a true business news organization would know, and there is an e-note in order to replace pull-replace by 'e-note':

https://pbs.twimg.com/media/BT_5S-TCcAA-EF2.jpg:large

So if your reposotory needs a e-note... ask Fox Business. They are in the know.

</humour>

Vlad L.
  • 154
  • 1
  • 9
VonC
  • 1,262,500
  • 529
  • 4,410
  • 5,250
  • 2
    -@VonC thanks for this. Would you mind providing some code to point out how what you've said differs from what I said? The `branch` vs. `master` decision seems like a critical one for taking my/Github's answer from a theoretical solution to something that one would actually use. – tim peterson Feb 04 '13 at 14:05
  • @timpeterson what you say what just the start (click here, submit). I wanted to detail the *process* of contributing in isolation. I have done so several times for GitLab: https://github.com/VonC/gitlabhq/commit/b40738cafdfef1c1869936b561ff5123f8ae21cb (few small commits in their own branch, since then deleted). Check the pull requests on that project: https://github.com/gitlabhq/gitlabhq/pulls – VonC Feb 04 '13 at 16:33
  • 1
    @timpeterson the fact that you can *completely* change the history within that branch, and that it will update the pull request automatically, is key here: because a pull request must be done on the latest of the upstream project. If that upstream repo has new commits, you must rebase your branch on top of it (changing the history of that branch), and push it back to your fork: that will update your pull request (based on that same branch) automatically. – VonC Feb 04 '13 at 16:35
  • 4
    I'm not understanding the rebasing part. What does that do? ([this page](http://git-scm.com/docs/git-rebase) makes it sound like rocket science but I believe it's not). What command would you issue at that point that "rebases"? – Camilo Martin Aug 01 '14 at 01:40
  • @CamiloMartin it moves your PR branch on top of the updated upstream branch (the one coming from the original repo): once you force push that moved branch to your fork, the PR will automatically adjust its history. See for instance http://stackoverflow.com/a/3903835/6309, http://stackoverflow.com/a/3611349/6309 – VonC Aug 01 '14 at 05:26
  • @VonC So `rebase` is what makes sure that anything I commit to my branch updates the pull request on GitHub, right? Do I have to do that again if the original repo recieves commits? (Also, again, what does the `rebase` command look like?) Thanks for the explanation. – Camilo Martin Aug 02 '14 at 19:10
  • @CamiloMartin yes, you would rebase your local branch each time you fetch from the upstream repo. You can see the rebase command at http://stackoverflow.com/a/3903835/6309. – VonC Aug 02 '14 at 19:12
  • @VonC Do you usually run the three commands (`fetch`/`merge`/`rebase`), or is `git pull --rebase` equivalent? (or is it `git pull --rebase upstream/master`?) – Camilo Martin Aug 02 '14 at 19:36
  • 1
    @CamiloMartin if you are on your PR branch, then a `git pull --rebase upstream/master` is fine indeed. – VonC Aug 02 '14 at 19:36
  • hey @VonC I was going over the pull request [tutorial](https://help.github.com/articles/using-pull-requests/) on github.. I got a question though: is there a way to make a pull request to a *specific* user? i got a private github repo and i want code reviews to be constrained between two engineers at a time.. rather than a group discussion process (ie similar to Atlassian Crucible and Review Board etc) – abbood Jan 28 '15 at 08:12
  • @abbood not that I know of. You could set an intermediate repo accessible just by that user, in order for him/her to do the pull request, but that wouldn't scale well. – VonC Jan 28 '15 at 08:21
  • Plase, can anybody explain the "rebase that branch" step? Where "click" it at Github? I have a good `https://github.com/MyUser/MyProject/tree/MyBranch` but never see any "rebase" or "merge", etc. navigating. – Peter Krauss Mar 21 '15 at 14:55
  • @PeterKrauss I gave a full example in http://stackoverflow.com/questions/17446004/github-need-help-on-giving-pull-request – VonC Mar 21 '15 at 15:29
  • @VonC thanks (!)... And sorry, I not understand and can't test (destroy) my repo... Do you have a simple (only simple) answer for [this](http://stackoverflow.com/q/29184227/287948) or [this](http://stackoverflow.com/q/29184375/287948) question? – Peter Krauss Mar 21 '15 at 15:37
  • this answer is very confusing for someone who hasn't done this before - it doesn't really explain which branches & repos to work on, nor what is going on – Richard Le Mesurier Aug 18 '15 at 09:43
  • @VonC Can you please clarify "..Don't create a pull request from master..." Thanks – vikramvi Jun 01 '16 at 15:48
  • 1
    @vikramvi master is a branch in common with the original repo that you have forked. That branch should always mirror the original repo. You isolate your fixes in a branch for your PR. You use master only as a way to know what is in the original repo (and to rebase your fix branch on top of it, to ensure an easy pull-request merge) – VonC Jun 01 '16 at 16:46
208

To learn how to make a pull request I just followed two separate help pages on Github (linked below as bullet points). The following command line commands are for Part 1. Part 2, the actual pull request, is done entirely on Github's website.

$ git clone https://github.com/tim-peterson/dwolla-php.git
$ cd dwolla-php
$ git remote add upstream https://github.com/Dwolla/dwolla-php.git
$ git fetch upstream
// make your changes to this newly cloned, local repo 
$ git add .
$ git commit -m '1st commit to dwolla'
$ git push origin master

  • Part 1: fork someone's repo: https://help.github.com/articles/fork-a-repo

    1. click the 'fork' button on the repo you want to contribute to, in this case: Dwolla's PHP repo (Dwolla/dwolla-php)
    2. get the URL for your newly created fork, in this case: https://github.com/tim-peterson/dwolla-php.git (tim-peterson/dwolla-php)
    3. type the git clone->cd dwolla-php->git remote->git fetch sequence above to clone your fork somewhere in your computer (i.e., "copy/paste" it to, in this case: third_party TimPeterson$) and sync it with the master repo (Dwolla/dwolla-php)
    4. make your changes to your local repo
    5. type the git add->git commit->git push sequence above to push your changes to the remote repo, i.e., your fork on Github (tim-peterson/dwolla-php)

  • Part 2: make pull-request: https://help.github.com/articles/using-pull-requests

    1. go to your fork's webpage on Github (https://github.com/tim-peterson/dwolla-php)
    2. click 'pull-request' button
    3. give pull-request a name, fill in details of what changes you made, click submit button.
    4. you're done!!
cpz
  • 1,002
  • 2
  • 12
  • 27
tim peterson
  • 23,653
  • 59
  • 177
  • 299
  • 4
    -@alexgray, i left the bash prompts, e.g., `Tims-MacBook-Pro:third_party TimPeterson$` because this is a beginner's tutorial and those prompts help orientate the user. – tim peterson Jul 06 '13 at 19:49
  • 1
    Yes. Thank you. A working example I can follow. Why don't you have that git hub? – Robert Johnstone Apr 05 '15 at 10:47
  • After `git fetch upstream`, don't you need to merge upstream changes with your local copy, using `git checkout master` then `git merge upstream/master`? – Sparhawk May 17 '15 at 05:02
  • @Sparhawk No, you do not need to merge your changes into the master that resides in your fork. The pull request to the other repo can be based solely off of the branch. However, it will usually be good practice for you to also update your fork's master as you go, so that changes to the "real" repo and frequently brought back in the loop in your forked repo. – ely Jan 30 '16 at 18:21
  • That would be `git push upstream master` and not `git push origin master`. – geekchic Apr 11 '16 at 18:47
  • How shall I do it right from the Terminal? Is there any way to use entire git without opening the browser? – Himanshu Shekhar May 19 '16 at 11:40
  • 1
    @HimanshuShekhar yes but you need to use the github desktop app or their API. The browser is easier for me. – tim peterson May 19 '16 at 14:58
  • In step 3 you have us use the git CLI. Can I use GitHub website to do all the operations? If not, can I use GitHub Desktop (I'm on Windows)? I'm looking for a simple way to do pull requests, and this procedure isn't very simple. – David Spector Jan 27 '19 at 15:46
70

In order to make a pull request you need to do the following steps:

  1. Fork a repository (to which you want to make a pull request). Just click the fork button the the repository page and you will have a separate github repository preceded with your github username.
  2. Clone the repository to your local machine. The Github software that you installed on your local machine can do this for you. Click the clone button beside the repository name.
  3. Make local changes/commits to the files
  4. sync the changes
  5. go to your github forked repository and click the "Compare & Review" green button besides the branch button. (The button has icon - no text)
  6. A new page will open showing your changes and then click the pull request link, that will send the request to the original owner of the repository you forked.

It took me a while to figure this, hope this will help someone.

Farhan
  • 1,561
  • 14
  • 12
  • 3
    It was unclear to me that you needed to fork a repo before being able to make a pull request. I figured a pushed commit would just go to some sort of pending branch that has public write access and then merged in from there. Thanks! – Chris Arena Mar 28 '15 at 09:49
17

I've started a project to help people making their first GitHub pull request. You can do the hands-on tutorial to make your first PR here

The workflow is simple as

  • Fork the repo in github
  • Get clone url by clicking on clone repo button
  • Go to terminal and run git clone <clone url you copied earlier>
  • Make a branch for changes you're makeing git checkout -b branch-name
  • Make necessary changes
  • Commit your changes git commit
  • Push your changes to your fork on GitHub git push origin branch-name
  • Go to your fork on GitHub to see a Compare and pull request button
  • Click on it and give necessary details
sudo bangbang
  • 27,127
  • 11
  • 75
  • 77
16

For those of us who have a github.com account, but only get a nasty error message when we type "git" into the command-line, here's how to do it all in your browser :)

  1. Same as Tim and Farhan wrote: Fork your own copy of the project: Step 1: Fork
  2. After a few seconds, you'll be redirected to your own forked copy of the project: Step 2
  3. Navigate to the file(s) you need to change and click "Edit this file" in the toolbar: Step 3: Edit a file
  4. After editing, write a few words describing the changes and then "Commit changes", just as well to the master branch (since this is only your own copy and not the "main" project). Step 4: Commit changes
  5. Repeat steps 3 and 4 for all files you need to edit, and then go back to the root of your copy of the project. There, click the green "Compare, review..." button: Step 5: Start submit
  6. Finally, click "Create pull request" ..and then "Create pull request" again after you've double-checked your request's heading and description: enter image description here
Sphinxxx
  • 12,484
  • 4
  • 54
  • 84
4

I followed tim peterson's instructions but I created a local branch for my changes. However, after pushing I was not seeing the new branch in GitHub. The solution was to add -u to the push command:

git push -u origin <branch>
tamalet
  • 657
  • 6
  • 5
2

I wrote a bash program that does all the work of setting up a PR branch for you. It performs forking if needed, syncing with the upstream, setting up upstream remote, etc. and you just need to commit your modifications, push and submit a PR.

Here is how you run it:

github-make-pr-branch ssh your-github-username orig_repo_user orig_repo_name new-feature

You will find the program here and its repository also includes a step-by-step guide to performing the same process manually if you'd like to understand how it works, and also extra information on how to keep your feature branch up-to-date with the upstream master and other useful tidbits.

stason
  • 5,409
  • 4
  • 34
  • 48
0

The Simplest GitHub Pull Request is from the web interface without using git.

  1. Register a GitHub account, login then go to the page in the repository you want to change.

  2. Click the pencil icon,

    search for text near the location, make any edits you want then preview them to confirm. Give the proposed change a description up to 50 characters and optionally an extended description then click the Propose file Change button.

  3. If you're reading this you won't have write access to the repository (project folders) so GitHub will create a copy of the repository (actually a branch) in your account. Click the Create pull request button.

  4. Give the Pull Request a description and add any comments then click Create pull request button.
flywire
  • 1,155
  • 1
  • 14
  • 38