How to pull request for git dummies
===

This tutorial includes
* How to raise a PR
* How to squash unneeded commits
* How to keep your PR branch updated
* How to stash unstaged changes
* PR etiquettes

## How to raise a PR

#### 1\. Fork the Repo
#### 2\. Clone the forked Repo to local
#### 3\. Make a new branch from master by `git checkout -b newbranch`

Now `git status` would emit message saying

On branch newbranch
nothing to commit, working tree clean

If you hope to submit a PR based on another branch, then use `git checkout anotherbranch` to switch to that branch, and make a new branch by `git checkout -b newbranch`.

Replace `newbranch` with your own comprehensive names.

#### 4\. Make changes and add necessary files


`git status` would show the changed files, if you hope to include the change in your PR, add the file by `git add <filename>`


In case all changes in the working directory are to be included, use `git add -A`, and use `git add -u` to modify the added entries but not any new files.

#### 5. Write your commit message

`git commit -m "A simple commit message"` or `git commit -a` will enter vim editor.

There are plenty of articles on how to write good commit messages, e.g., [this article](https://chris.beams.io/posts/git-commit/). But it is good commit messages if it's comprehensive enough for your teammates and you.

#### 6. Push to your branch

`git push origin newbranch` replace newbranch by your branch name.


#### 7\. Raise a PR on github


Even monkeys won't need explaination at this step.

## How to squash unneeded commits

You can update the PR by push more commits to the branch you've been working on. Deleting the branch will cause the PR to be closed.


#### git rebase -i HEAD~2
There are two commits as the capture shows, and what if we hope to merge the two commits as one? To keep the commited changes, but having only one commit message instead of two, `git rebase -i HEAD~2` will do the work.



`Commmmmit` is the newer commit, and we hope to squash it.

#### Change the `pick` to `squash` and use `:wq` to quit vim.


#### Change the commit message


I removed the 2nd commit message `Commmmmit` and only kept the 1st one.


#### git push --force origin newbranch

Once again, you changes in the newer commit will not be abandoned, but remain in the new commit.


But as you can see here, the hash has changed to `ab75e2a` from `47b8475`

## How to keep your PR branch updated

At times another PR merged into master before yours do, so your branch can be left behind the master branch. You are supposed to keep your branch updated to be merged.

#### See if you've added upstream repo


Here I've only have origin but no upstream. Upstream is where I want to get updated from and where I want to merge into.


#### Add upstream by `git remote add upstream <link to repo>`

#### Update your master and your new branch

git checkout master         # switch to master branch
git pull upstream master    # update master to upstream master
git checkout newbranch      # switch to new branch
git rebase master           # rebase master to this branch


#### Sovle conflicts

Use `git status` to review the files that have conflicts


Solve the conflicts.


Divided by `=======`, below is your changes in your term, and above is what's new in the updated master branch.


Modified the file to satisfactory condition.

git add Readme.md
git rebase --continue             # rebase fails if not all conflicts are solved
git push --force origin newbranch # update the branch

## Stash unsaved changes

In case I made changes but still wish to switch another branch.

git stash                    # saving working directory
git checkout otherbranch
# and then do something
git checkout newbranch       # switch back
git stash pop                # restore the changes I made

## PR etiquettes

* Don't leave the PR description blank
* Keep commits clean, and the fewer the better
* Don't ping maintainers too often
* Make your branch ready to be merge before you raise it.