4. The Commit

4.1. Properties Of A Commit

In Git a commit exists of different things. Of course there are the files you want to change, but there are also other properties.

../_images/commit.svg

4.1.1. Changeset

Each commit contains a list of file & directory changes. These changes are grouped together and are called changeset.

4.1.2. Message

Each commit contains a message, which exists of a summary (sometimes also called subject) and description. There are similarities to emails, since the first line is the summary, separated by an empty newline from the description.

Hint

You should think about having some guidelines for Git commit messages for the following reasons:

  • It makes it easier to find commits

  • It makes it easier to identify what changed

  • You can do Semantic Versioning

  • You can automatically generate changelogs

We’ve some strict guidelines for Commit messages.

4.1.3. Author & Committer

Each commit contains an author and a committer. For both - the author and committer - a name & email address is stored in the commit. While the author is usually identical to the committer, they might differ in certain situations (e.g. delegation of work, during merge requests & rebases).

You may be wondering what the difference is between author and committer. The author is the person who originally wrote the work, whereas the committer is the person who last applied the work. So, if you send in a patch to a project and one of the core members applies the patch, both of you get credit – you as the author, and the core member as the committer. [1]

Hint

You can set your name & email address via the Git Configuration. Have a look at the User & Email section.

4.1.4. Timestamps

Each commit contains 2 timestamps of the changes:

  • Author timestamp: Matches the date & time when the author authored/committed the changes

  • Commit timestamp: Matches the date & time when the committer committed the changes

4.1.5. SHA Hash

Each commit will get its own identifier which is called SHA Hash. As the name already implies, the SHA Hash is a computed / hashed value.

A SHA hash exists of 40 characters, but they can also be shortened by removing trailing characters. Git commands will work with shortened SHA hashes, as long as they’re unique. A sample SHA hash looks like this:

39f07fdffa5fff3cdc355bf5379573dce5530ae4
39f07fd

When working with Git, SHA hashes are used all the time to identify commits or alike.

Hint

In Git the following properties will be included in the computation of the hash:

  1. The tree to which it refers to, i.e. the branch name

  2. The SHA hash of the parent commits

  3. The commit message

  4. The author name, email & timestamp

  5. The committer name, email and timestamp

4.2. The Who, When, What & Why and How

When looking at real world examples of software development, the following questions might arise:

  • Who changed something?

  • When were these changes introduced?

  • What exactly changed?

  • Why did somebody change this?

  • How exactly did somebody change that behaviour?

With a single commit, all of those questions can be answered if done properly:

4.3. A Proper Message

We have our own guidelines for Commit messages.

Please note, it is crucial that you describe what you did and why you did it. You should never describe how you did it, since this is included in the changeset.

Hint

Example

Let’s say you’ve a public-facing application, which is configured via a config file. This config file contains a setting for debugging IP addresses, which was set to a wildcard *, which means the application was running in debug mode for all users.

Now a smart cookie came along and found out, that any user was able to fetch sensitive data when debug mode was activated, and opens an issue. A developer picked up the issue, fixed the application and committed it with the following message:

removed * from config file

This commit message is quite useless, since you already see the change in the changeset:

--- before      2022-09-24 17:16:35.000000000 +0200
+++ after       2022-09-24 17:16:56.000000000 +0200
@@ -1,3 +1,3 @@
 DEBUG_IPS=[
-    '*',
+    '127.0.0.1',
 ]

Wouldn’t it be better if the developer did a message like this:

FIX: Disabled debug mode for all users

The debug mode leaks sensitive informations and should never be
activate for all users.

Please have a look at issue #123

Let’s see what this commit message does for us:

  • It describes what we did (i.e. disabled debug mode)

  • It describes why we did it (i.e. fix for leak)

  • It also points to an issue, which might contain all discussions

  • It might automatically push notifications to the issue (since #123 is picked up automatically)

But not only that. Let’s imaging another developer might come back from holidays and doesn’t understand why his debug mode no longer works. He checks the commit messages / changes and sees why this was changed.