Contents

Git Commit Messages

Git Commit Messages

Git Template

See Customizing Git configuration.

Subject line (try to keep under 50 characters)

Multi-line description of commit,
feel free to be detailed.

[Ticket: X]

Conventional Commit Message

Conventional commit message follows the structure:

[subject line]

[optional body]

[optional footer(s)]

Subject Line

Subject line gives a short summary (72 characters or less), describing the commit. Follows convention, e.g. Semantic Commit Messages (see below).

As Angular suggests: “It should be present tense. Not capitalized. No period in the end.”, and imperative like the type.

As Chris Beams mentions in his article about commit messages, the summary should always be able to complete the following sentence:

If applied, this commit will… add authorization for document access.

Body

Gives details on the change. Should be an imperative sentence explaining why we’re changing the code, compared to what it was before.

Format is multiline with line length 72 characters or less.

Semantic Commit Messages

Semantic Commit Messages define standard structure for the commit subject line. The Semantic Commit Message format goes hand in hand with semantic versioning.

          ┌─⫸ Subject: 72 characters or less.
          │
┌─────────┴─────────────┐
 <type>: <short summary>
   │           │
   │           └─⫸ Summary in imperative mood. Not capitalized.
   │                No period at the end. At least 20 characters.
   │
   └─⫸ Commit Type: build|ci|deprecate|docs|feat|fix|other|perf|
                     refactor|release|style|test

Commit Types

  • build: (changes related to the build system)

  • ci: (changes related to the continuous integration and deployment system)

  • docs: (changes to the documentation)

  • feat: (new feature for the user, not a new feature for build script)

  • fix: (bug fix for the user, not a fix to a build script)

  • other: (anything not covered by other types – use as a last resort!)

  • perf: (changes related to backward-compatible performance improvements)

  • refactor: (refactoring production code, eg. renaming a variable)

  • release: (making a release, e.g. bumping the package version for release)

  • style: (formatting, missing semi colons, etc; no production code change)

  • test: (adding missing tests, refactoring tests; no production code change)

  • deprecate: (mark some code as deprecated)

Note

Imperative is used to give a command, instruction or make a request.

The imperative is formed with the verb in base form (without “to”) without a subject. Imperative sentencies could be affirmative or negative to indicate prohibitions. The negative imperative is formed with “do not” or “don’t” and the verb.

Semantic Commit Messages++

Adds optional scope, breaking change indicator and PR (pull request) number.

                       ┌─⫸ Subject: 72 characters or less.
                       │
┌──────────────────────┴────────────────────────┐
 <type>(<scope>)!: <short summary> (<PR number>)
   │       │    │        │              │
   │       │    │        │              └─⫸ Optional Pull request number.
   │       │    │        │                   E.g. #765
   │       │    │        │
   │       │    │        └─⫸ Summary: Same as Semantic Commit Message
   │       │    │
   │       │    └─⫸ Optional breaking change indicator.
   │       │
   │       └─⫸ Optional Commit Scope: Module, package, component, area or
   │                                   issue number, e.g. #123.
   │
   └─⫸ Commit Type: Same as Semantic Commit Message.

Linting Commit Messages

https://jorisroovers.com/gitlint/

Browsing History

Git provides us the power to browse the repository commit history - so we’re able to figure out what actually happened, who contributed and so on.

Let’s see how the conventions might ease up the browsing:

$ git log --oneline --grep "^feat\|^fix\|^perf"

We use the commit message type to filter out and so showing only the production changes (all of the messages that start with feat, fix or perf).

Another example:

$ git log --oneline --grep "^feat" | wc -l

previous

Coding Style

next

Documentation with Sphinx