Branching and Merging

Git history is similar to code in that it is written once but it is read dozens of times. Therefore, we optimize for readability. It should be clear what happened, by whom, when, and ideally why.

Start all work in a new branch off of master

git fetch
git checkout -b your_branch_name origin/master

Rebase onto master daily

This reduces merge conflicts in the future.

# on your_branch_name
git fetch
git rebase origin/master

Clean up your commits before creating a PR

When working locally, do whatever you want. Before sharing, clean up your history into logical commits and write good commit messages for them. Focus on clarity for someone reading this 3 months from now.

# on your_branch_name
git fetch
git rebase -i origin/master
git push -u origin your_branch_name

Tip: make lots of small commits as you work, then squash them into one or several bigger commits before pushing. This helps organize your work, so that logically separate changes can be placed into separate commits without manually splitting an existing commit.

Rebase and non-ff-merge into master when you're done

We want a merge commit present for all code merged from PRs, even if that PR is properly rebased and only a single commit. The merge commit documents that the merge came from a PR. This helps us differentiate between commits to straight master.

# on your_branch_name
git fetch
git rebase origin/master
# if there are conflicts at this point, ask the PR creator to fix them. run `git rebase --abort` to abort
# if no conflicts, proceed ...
git checkout master
git pull
git merge --no-ff your_branch_name

Example

Here's an example of a commit graph that's easy to follow and understand. Notice how it's immediately obvious which commits were made directly in master and which groups of commits came from a single PR.