What are semantic messages in Git?

Question

Eventually, when I browse some of the Github repositories, I come across certain messages from commit standardized:

feat(*): initiate re-write

Or:

refactor(*): remove unwanted files

What are these words (feat, refactor...) preceding the message itself?
There are others, but I only mentioned two of them.

---

With a brief search, I was able to conclude that these are messages from commit semantics. But what are the rules for using them? And how to use them in the right way?

Answer 1

The semantic commits as you described were proposed in an Angularjs convention document. They have been documented and widely used by Karma, a project open source testing for Javascript. Today, many community-maintained projects use it, adapting to its uses.

As guidelines recommend the use of such conventions in the commit for:

1. Automatic generation of changelog
2. Easy browsing in Git history

The message pattern of commit proposed semantic is:

<tipo>(<escopo>): <assunto>

<corpo>

<rodapé>

Being <tipo> of the following values:

1. feat: when it comes to a new functionality (from English, Feature)
2. fix: when it comes to a correction of bug
3. docs: when a change is made to the documentation
4. style: when it comes to code formatting
5. refactor: when it comes to code refactoring in production
6. test: when adding or refactoring tests, without impact on code in production
7. chore: when adding or editing tasks Grunt, or Webpack, also without impact on production

The <escopo> is optional, especially if the change is global, but good examples would be init, runner, watcher, config, web-server, proxy, etc..

To the <corpo> of the message of commit is recommended:

1. Use the imperative form in the present tense. Prefer "change" to "changed" or "changes"
2. Include reasons for code changes compared to previous behavior

The <rodapé> can be dedicated to important notes and warnings, as if there are radical changes in the code that fit a note. For example:

MUDANÇA RADICAL:
A opção `port-runner` da linha de comando mudou para `runner-port`, para que permaneça consistente com a sintaxe do arquivo de configuração.
Para migrar seu projeto, mude todos os comandos, onde você usa `--port-runner`, para `--runner-port`.

Can also be used for integrations, such as close issues on Github using the commit message.

Closes #123, #456, #789

As an open source initiative, these guidelines are held by the community and opined in articles. One of the most influential is the Sparkbox’s Semantic Commit Messages.

See how a minor change to your commit message style can make you a Better Programmer. I use the Rigid commit message format, and it makes me a Better Programmer. You’ll Never Again be tempted to include a bug fix and a Feature in the same commit. My git log is now an easy-to-skim changelog.

An example of a commit following this pattern:

fix($compilação): testes unitários no IE9

Versões mais antigas do IE serializam HTML com tudo maiúsculo, mas o IE9 não.
Seria melhor esperar um *case insensitive*, mas o Jasmine não aceita expressões regulares.

Closes #392
MUDANÇA RADICAL: quanto ao foo.bar, foo.baz deve ser utilizado ao invés disso.

Answer 2

Use on Node.js

Just adding the answer of Vinicius, for those who have interest in following the commit standardized using Node.js, there is a package in NPM called git-commit-msg-linter . This package makes the linter messages to keep them in Angular Commit Message Guidelines. I’ll also show you how to customize the package functionality settings to allow certain types, add new types, type description messages, and set the maximum message size for commit.

How to use git-commit-msg-linter

Do the package installation:

npm install git-commit-msg-linter --save-dev

No extra configuration is required, it is sufficient that the git Repository is already initialized in the project folder.

The package informs the message format of commit to be followed:

^{Adapted translation}

<type>(<scope>): <short summary>
  │       │             │
  │       │             └─⫸ Summary.
  │       │
  │       └─⫸ Commit Scope.
  |                          
  │
  └─⫸ Commit Type.: feat|fix|docs|style|refactor|test|chore|perf|ci|build|temp

• Summary: Summary at present time. Without capital letters. No end in the end.

• Commit Scope: Optional, it can be anything specifying the scope of the confirmation change. For example $ location | $ browser | $ compile | $ rootScope | ngHref | ngClick | ngView, etc. In application development, the scope can be a page, module or component.

• Commit Type: These are the guys Vinicius mentioned, feat | fix | docs | style | refactor | test | chore | perf | ci | build | temp.

Obs: The fields type and short summary are mandatory.

We have some examples:

• Bad: The package throws an error and does not do the commit of the message.

$ git commit -m "Correct spelling of CHANGELOG."

The commit in the above format will not be valid and the package will launch an error:

************* Invalid Git Commit Message **************
  commit message: adding git
  correct format: <type>[scope]: <subject>
  example: docs: update README to add developer tips

  type:
    feat     A new feature.
    fix      A bug fix.
    docs     Documentation only changes.
    style    Changes that do not affect the meaning of the code (white-space, formatting, missing semi-colons, etc).
    refactor A code change that neither fixes a bug nor adds a feature.
    test     Adding missing tests or correcting existing ones.
    chore    Changes to the build process or auxiliary tools and libraries such as documentation generation.
    perf     A code change that improves performance.
    ci       Changes to your CI configuration files and scripts.
    build    Changes that affect the build system or external dependencies (example scopes: gulp, broccoli, npm).
    temp     Temporary commit that won't be included in your CHANGELOG.

  scope:
    Optional, can be anything specifying the scope of the commit change.
    For example $location, $browser, $compile, $rootScope, ngHref, ngClick, ngView, etc.
    In App Development, scope can be a page, a module or a component.

  subject:
    Brief summary of the change in present tense. Not capitalized. No period at the end.

Note that the message has an end point (.) and starts with a capital letter (C).

• Good: Lower cases are accepted.

$ git commit -m "docs: correct spelling of CHANGELOG"

$ git commit -m "docs(CHANGELOG): correct spelling"

The package has default settings such as accepted types and maximum message size commit (by default, the maximum is 100), but this can be easily customized according to the developer’s need. Just create a file commitlinterrc.json and define the rules to be used by the package.

Example:

{
  "types": {
    "feat": "Nova funcionalidade do projeto",
    "build": "Nova build do projeto",
    "docs": "Nova documentacao do projeto",
    "testando": "Novo tipo pode ser usado",
    "temp": false,
    "chore": false
  },
  "max-len": 120,
  "debug": true
}

• In "types", we define the types that will be accepted in the scope type of messages.

• In "feat", for example, I changed and put a description of this type that will serve as a query if someone makes a commit wrong. Description:

  ^{new functionality of the project}

• In "temp" and "chore" equal to false, I define that these types cannot be used in commits.

• In "testando" i set a new type that can be used in type messages, and I put a description of this type.

• "max-len" i set the new such maximum for messages.

Now, every time I write one commit in format not accepted, we will have the following error in the terminal:

$ git c "chore: adding gitignore file"

^{Notice that chore is not accepted.}

Exit:

[DEBUG] config: {
  types: {
    feat: 'Nova funcionalidade do projeto',
    build: 'Nova build do projeto',
    docs: 'Nova documentacao do projeto',
    testando: 'Novo tipo pode ser usado ',
    temp: false,
    chore: false
  },
  'max-len': 120,
  debug: true
} 
[DEBUG] commit message: |chore: adding gitignore file| 
[DEBUG] type: chore, scope: undefined, subject: adding gitignore file 

  ************* Invalid Git Commit Message **************
  commit message: chore: adding gitignore file
  correct format: <type>[scope]: <subject>
  example: docs: update README to add developer tips

  type:
    feat     Nova funcionalidade do projeto
    fix      A bug fix.
    docs     Nova documentacao do projeto
    style    Changes that do not affect the meaning of the code (white-space, formatting, missing semi-colons, etc).
    refactor A code change that neither fixes a bug nor adds a feature.
    test     Adding missing tests or correcting existing ones.
    perf     A code change that improves performance.
    ci       Changes to your CI configuration files and scripts.
    build    Nova build do projeto
    testando Novo tipo pode ser usado 

  scope:
    Optional, can be anything specifying the scope of the commit change.
    For example $location, $browser, $compile, $rootScope, ngHref, ngClick, ngView, etc.
    In App Development, scope can be a page, a module or a component.

  subject:
    Brief summary of the change in present tense. Not capitalized. No period at the end.

Note that the "debug": true shows us the contents of .json configuration, in addition to additional information prefixed with [DEBUG].

In the type, we have the types and descriptions we customize, in addition to those that come by default.

For more information about customizing messages, see the NPM link.

I hope this answer is of interest to someone. I especially like and use this package because we can customize types, descriptions, message sizes commit which makes it the git well friendlier, even more so for beginners who start using it and for teams who wish to create their own patterns in their projects.

:)