Squashing Commits

We try to keep the history for PDF.js relatively clean and we may ask contributors to "squash" their commits before we merge.

Note: These directions assume that you named the Mozilla pdf.js repo (not your fork) upstream and you have a branch called super-feature. See Contributing for details.

1. Simple case (no merge commits) - say you have three commits in your pull request and you want to squash them into one commit:

git rebase -i HEAD~3

Change pick to squash (or fixup) for last two and update the commit message in the editor, then git push --force origin super-feature.

1. Advanced case (merge commits) - say you have three commits but one of them was a merge commit: This can be avoided if you use git pull --rebase upstream master instead of a regular git pull upstream master.

# fetches the current upstream repository
git fetch upstream
# resets HEAD to the current upstream
git checkout upstream/master
# merges all commits from the local branch
git merge --no-commit --squash super-feature
# re-creates the branch starting from current HEAD (old commits will be lost)
git checkout -B super-feature
# lets you edit the commit and checks in the changes (you can also use git commit -m "message")
git commit -e
# pushes the changes (in general, be careful with the --force parameter)
git push --force origin super-feature

Alternatives

1. Add the following to your git config. Either the global one or the config within your pdf.js fork (.git/config).

[alias]
	squash = !sh -c 'git checkout upstream/master && git merge --no-commit --squash $0 && git checkout -B $0 && git commit -e'

1. Then you simply need to do:

git merge upstream/master
git squash super-feature

1. That will bring up your editor to allow you to put in the commit message you want. After entering a commit message, press Esc and type :wq to exit the editor (if the editor is set to vim).

2. Then update the pull request:

git push --force origin super-feature

(Recovering from bad squashes)

Hopefully you did not do anything wrong, then you don't need to read this section :) If you did something wrong and you end up with lots of commits you don't recognize. Don't panic:

1. Find your last commit sha/id before you did squashing (e.g. 'abcde123'). The pull request github page will help you with that in the list of the commits (or diff comments). And then just run:

git commit -B super-feature abcde123

2. Or, you can just cherry-pick your commits into up-to-date upstream master (e.g. you see 'abcdef123' and 'defghi567' as your commits):

# fetches the current upstream repository
git fetch upstream
# reset your branch to upstream master
git checkout -B super-feature upstream/master
# cherry-pick only your commits and resolve conflicts
git cherry-pick abcdef123
git cherry-pick defghi567
# optionally rebase can be run, in this case git rebase -i HEAD~2

And repeat squashing.