What would be the best practices for commits in Git?

Question

There are best practices to perform commits and write comments on these commits, for better communication and understanding during the software development process?

Answer 1

Granularity of commits

As I said before here, The main good practice is to try to commit one feature at a time, regardless of whether you changed one or 10 files. In this way it would be possible to reverse a change in case of problems, which is not as rare as one thinks.

Note that change in many files at the same time is symptomatic that could divide the change into parts.

Commentary

I am not in favour of great explanations in comments from commits.

What I recommend is a high-level explanation of at most one line of what has been done, as a mental note, from which the developer can remember or at least look for the specification of that change.

Content of the comment

Something used in virtually every company that takes the process seriously, be it agile or traditional, is to link each commit to a ticket or Issue of some system like Jira, Mantis or Bugzilla.

Each ticket is, in turn, linked to a specific task or a whole user story, depending also on the granularity in which the project is planned.

Thus, the developer can easily consult the documentation and possible discussion on the bug or functionality. It is also possible to track in the version management system what changes were necessary to implement the functionality X.

Tooling

Most Ides have integration with tickets and, properly configured, are able to automatically add to the commit the number of ticket what the developer is working on.

It is also possible to configure a rule in the versioning system to prevent commits are made without comment and without link with any ticket registered.

In general I do not recommend such a level of control, but it is common in large companies to prevent inexperienced developers from doing commits undue.

Answer 2

To documentation "official"¹ git has a recommendation about commits and messages. They are a set of good practices to make the nevegação by the history of the project easier to assimilate.

Although they are not mandatory, they are widely applied and replicated on the Internet:

1. Check whitespace issues in the code
   That’s easy, just run git diff --check before the commit, and any extra spacing error will be listed.

2. Commits must be small and complete code changes
   Two things to keep in mind is that a commit should always work on its own. If you have implemented a feature that took 20 commits, each of them must add (or remove) a part completely, and the program must remain fully functional. This does not mean that commits should be huge, containing hundreds of altered lines over days. Try to make small and incremental changes.

3. Message format²
   This is as essential a part as the others. A project that maintains the same message pattern is easier to understand and follow. It doesn’t make much sense to be the only person on the project working like this... If you get everyone to write the messages in this format, everything will be easier:

   1. 1 line spacing between the commit title and the rest of the message
   2. The title must not exceed 50 characters
   3. The title should start with a capital letter
   4. The title should not end with '.'
   5. The title must be in the gift of the second person:
      Instead of "I added tests to" or "Adding tests to", use "Adds tests to"
   6. Message body should not be larger than 72 characters wide
   7. Body of the message should explain what and why, nay as.

   The example in the git documentation:

   Breve (50 caracteres ou menos) resumo das mudanças
   
   Texto explicativo mais detalhado, se necessário. Separe em linhas de
   72 caracteres ou menos. Em alguns contextos a primeira linha é
   tratada como assunto do e-mail e o resto como corpo. A linha em branco
   separando o resumo do corpo é crítica (a não ser que o corpo não seja
   incluído); ferramentas como rebase podem ficar confusas se você usar
   os dois colados.
   
   Parágrafos adicionais vem após linhas em branco.
   
    - Tópicos também podem ser usados
   
    - Tipicamente um hífen ou asterisco é utilizado para marcar tópicos,
      precedidos de um espaço único, com linhas em branco entre eles, mas
      convenções variam nesse item
   

The final tip is that if you register a default git pro editor with git config --global core.editor vim (for example), git is likely to start the editor with the format settings loaded, to warn you if you run out of the format.

---

^{1. The documentation on git-scm.com is derived from a book that was not written by the authors of git, but for all intents and purposes is considered the official documentation. The Portuguese version is outdated, but that part hasn’t changed much.}

^{2. The list of formatting items is derived from How to Write a Git Commit Message (How to Write a Commit Message - in English). I like the way the list is organized, so I used it. But it follows all the recommendations of the official documentation}