This content originally appeared on DEV Community and was authored by ZigRazor
A commit should be a self-contained update to the code tree. Despite bug fixes that could be introduced later in the development, a commit should be never considered as "I’m saving my work now, I’ll continue later", especially if the commit is pushed to a remote repository.
On the other hand, a commit should not contain multiple changes to the code base.
If, during development, I have to change something in two different modules, and the changes are unrelated, then the changes should be placed in two different commits.
That is: make separate commits for logically separate changes.
Making good commits is a form of art. A good way to decide whether a commit is self contained, developers should answer themselves he question: "will I be able to cherry pick this commit in the future, shall I need it?". If the answer is yes, then most
likely it is a good commit.
Commit messages should be meaningful. A one-line commit message like "I’m developing foo" will not allow other developers to understand what that commit is for. A minimal
commit message would be of the format:
Short log
(Optional pointers to external resources, such as defect tracking)
The intent of your change.
(Optional, if it's not clear from above) how your change resolves the
issues in the first part.
Tag line(s) at the end.
This is an example of a good commit message:
foobar: Adjusted the foo setting in bar When using foobar on systems with less than a gigabyte of RAM common usage patterns often result in an Out-of-memory condition causing slowdowns and unexpected application termination.
Low-memory systems should continue to function without running into memory-starvation conditions with minimal cost to systems with more available memory. High-memory systems will be less able to use the full extent of the system, a dynamically tunable option may be best, long-term.
The foo setting in bar was decreased from X to X-50% in order to
ensure we don't exhaust all system memory with foobar threads.
Signed-off-by: Joe Developer <joe.developer@example.com>
Several things should be noted here. The minimal commit message is good for new code development and simple changes. An empty line must always come after it, otherwise post processing software might not be able to distinguish it from the rest of the
commit text.
The single short log message indicates what needed to be changed. It should begin with an indicator as to the primary item changed by this work, followed by a short summary of the change. In the above case we're indicating that we've changed the "foobar" item, by "adjusting the foo setting in bar".
The single short log message is analogous to the git "commit summary". While no maximum line length is specified by this policy, it is suggested that it remains under
50 characters wherever possible. Think of it as the subject of an email: you should never write too much text in it, otherwise receivers will not understand easily what the email is about.
Optionally, you may include pointers to defects this change
corrects. Unless the defect format is specified by the component you are modifying, it is suggested that you use a full URL to specify the reference to the defect information. Generally, these pointers will precede any long description, but as an optional item it may be after the long description. This could be a good way, for example, to refer to open issues in a bug tracker. You must then have a full description of the change.
Specifying the intent of your change and if necessary how the change resolves the issue.
Finally, one or more tag lines should exist. Each developer responsible for working on the patch is responsible for adding a Signed-off-by: tag line. This tag line should be added by people writing the patch, and additional tag lines should be added by
people, for example, merging the patch into different branches. This allows to easily track the updates to the code base, and determine who did what.
It is not acceptable to have an empty or non-existent header, or just a single line message. The summary and description is required for all changes. The commit messages should be manually indented. Usually, each line of the message, should not be longer than 78 characters. Note that in order to do this easily, is
always better to avoid using the -m switch when committing: in fact, simply issuing:
$ git commit
will fire up the text editor specified in the EDITOR environment variable (you can set it to your preferred editor), so that you can freely write your commit message respecting the adopted layout. Note that if you set your favorite editor to vim, you can add the following lines to ~/.vimrc:
filetype plugin indent on
au FileType gitcommit set tw=72
which automatically wraps the text to the specified 72 characters for git commit messages. To check whether vim is correctly identifying the commit message as gitcommit, the following command can be used within vi:
:set filetype?
or to save a few keystrokes:
:se ft?
If, for any reason, you have pushed commits with non-meaningful descriptions (due to hurry, pressure, git fire , etc.), these should never end up in the master branch.
Here, interactively rebasing you local branch (and issuing a force push if possible) is a good practice.
For More "The Final Guide" see the Index Page
This content originally appeared on DEV Community and was authored by ZigRazor
ZigRazor | Sciencx (2021-09-22T07:24:42+00:00) Git Commits and Commit Messages : The Final Guide. Retrieved from https://www.scien.cx/2021/09/22/git-commits-and-commit-messages-the-final-guide/
Please log in to upload a file.
There are no updates yet.
Click the Upload button above to add an update.