Skip to content
Permalink
Branch: master
Find file Copy path
Find file Copy path
Fetching contributors…
Cannot retrieve contributors at this time
161 lines (116 sloc) 6.3 KB
---
title: Git style guide
last_reviewed_on: 2019-05-17
review_in: 6 months
---
# <%= current_page.data.title %>
## Commit messages
Writing good commit messages is important. Not just for yourself, but for other
developers on your project. This includes:
* new (or recently absent) developers who want to get up to speed on progress
* interested external parties who want to follow progress of the project
* people in the public (remember, we code in the open) who want to see our work,
or learn from our practices
* any future developers (including yourself) who want to see why a change was
made
Capturing context around a change allows people to understand why a particular
implementation decision was made, much like an [architecture decision record](http://thinkrelevance.com/blog/2011/11/15/documenting-architecture-decisions). We're
being kinder to our future selves.
### Recommended blog posts on this topic
* [How to Write a Git Commit Message](https://chris.beams.io/posts/git-commit/)
* [5 useful tips for a better commit message](http://robots.thoughtbot.com/5-useful-tips-for-a-better-commit-message)
* [Every line of code is always documented](http://mislav.uniqpath.com/2014/02/hidden-documentation/)
### Content
A good commit message briefly summarises the "what" for scanning purposes, but
also includes the "why". If the "what" in the message isn't enough, the diff is
there as a fallback. This isn't true for the "why" of a change - this can be
much harder or impossible to reconstruct, but is often of great significance.
#### Example
``Set cache headers``
prefer:
```
Set cache headers
IE 6 was doing foo, so we need to do X.
See http://example.com/why-is-this-broken for more details.
```
#### Links to issue trackers
A link to a ticket in an issue tracker should not be seen as an alternative to
writing a commit message.
While a link can add some extra context for people reviewing
a pull-request, the commit message should stand on its own. There's no guarantee that
the link will continue to work in the future when someone is looking through the commit
history to understand why a change was made.
If you are adding a link to a publicly viewable repository, ensure that the linked
ticket is publicly viewable (and likely to remain so).
### Structure
Commit messages should start with a one-line summary no longer than 50
characters. Various Git tools (including GitHub) use this as the commit
summary, so you should format it like an email subject, with a leading capital
and no full stop. The Git convention is to write these in the present tense.
For example:
> Leverage best-of-breed synergies going forward
You should leave a blank line before the rest of the commit message, which you
should wrap at around 72 characters: this makes it easier to view commit
messages in a terminal.
#### Example
Taken from [Tim Pope’s guidelines](http://tbaggery.com/2008/04/19/a-note-about-git-commit-messages.html).
> Capitalized, short (50 chars or less) summary
> More detailed explanatory text, if necessary. Wrap it to about 72
characters or so. In some contexts, the first line is treated as the
subject of an email and the rest of the text as the body. The blank
line separating the summary from the body is critical (unless you omit
the body entirely); tools like rebase can get confused if you run the
two together.
> Write your commit message in the present tense: "Fix bug" and not "Fixed
bug." This convention matches up with commit messages generated by
commands like git merge and git revert.
> Further paragraphs come after blank lines.
> - Bullet points are okay, too
> - Typically a hyphen or asterisk is used for the bullet, preceded by a
single space, with blank lines in between, but conventions vary here
> - Use a hanging indent
## Branching/merging conventions
You may often choose to work on a particular feature on a "feature branch"
rather than directly on `master`. Indeed, given how cheap branches are in Git,
this is [positively encouraged](http://git-scm.com/book/en/Git-Branching-Basic-Branching-and-Merging).
You are encouraged to make liberal use of Git's [history rewriting
features](http://git-scm.com/book/en/Git-Tools-Rewriting-History) while working
locally, in order to arrange your commits into appropriate logical chunks that
will make sense to your fellow developers. In particular, you may find
`git rebase --interactive` very useful. You are also encouraged to avoid merge
commits and use git rebase master instead. However, you should not rewrite commits
that have been pushed unless you:
* are **very sure** that no-one else will be affected by you rewriting the
branch history
* have an Extremely Good Reason. For example: someone has committed
sensitive information (personally identifiable data, passwords and suchlike)
and it needs purging from history
When in doubt you should err towards smaller commits, which can be rebased
together later. It's harder to break large commits out into smaller chunks.
The smaller commits should still be logical chunks, but this will give context
for a more specific change and make git tools like `annotate` and `log` more
useful.
When merging from a feature branch to master (or any other mainline development
branch), in particular one that has previously been shared with colleagues, you
should use `git merge`'s `--no-ff` option to preserve evidence of your feature
branch in the repository history. This advice may be freely ignored for smaller
local feature branches for which a fast-forward merge will look like any other
routine development work on `master`.
## Don't use `git push -f`, use `--force-with-lease` instead
Force pushing in git is a subject that attracts all kinds of religious
battles. This advice is not about the merits of force pushing. This is about how
to use `git push -f` if and when you do use it.
Let's say you're working on a branch, 'foobar', and you decide to force push
to the remote. So you do this:
```
$ git push -f
```
If anyone else has committed anything to your branch since you last pulled, you
will blow their changes away.
So for a bit of safety, if you ever need to force push please instead do:
```
$ git push --force-with-lease
```
`--force-with-lease` [refuses to update a
branch](https://developer.atlassian.com/blog/2015/04/force-with-lease/) unless
it is the state that we expect; i.e. nobody has updated the remote branch.
You can’t perform that action at this time.