Commit Comments

From Coder Merlin
Within these castle walls be forged Mavens of Computer Science ...
— Merlin, The Coder

Introduction[edit]

Commit comments are an important part of Source Control that allows coders to document why and what changes (AKA "commits") were made.[1] But not all commit comments are helpful in recording what changes were made. Consider a non-technical analogy: you are applying to several different jobs in different industries as you explore different pathways. You have a myriad of valuable experiences that you want to showcase, but some are more relevant to one industry over another. In that case, you would have different versions of your resume for different use cases. But, if you do not label each resume appropriately, you will not know which resume to use in which case, and you will waste time in the future reviewing each document just to determine whether this is what you want to use.

In the case of coding projects, you will have several files, different methods and objects coded up perhaps in different languages (if you use something different for the front-end or back-end). If you or another coder needs to revisit this project at a later date, you will want to be able to know what each file does, and why. Quality commit comments will allow you to understand all of the changes you made (or anyone else on your team made), where parts of the code are stored, and how they affect each other so you can get back to work as quickly as possible.

Writing Your First Commit Comment[edit]

Navigating to the Correct Directory[edit]

In order to actually write a commit comment, you need to have an initialized git repository in the directory you are using to contain your project. First, make sure you are in your project directory. You can check this by using the following commands. pwd stands for "Print Working Directory." The command will yield a string showing you the directory that you are in.

jane-williams@codermerlin:~$ pwd

/home/jane-williams 

If this is not the directory that you would like to be in, and you are unsure how to navigate, try using ls. This command will list all of the files and directories that are in your current directory.

jane-williams@codermerlin:~$ ls

firstfile.txt  myProject 

To navigate to your project directory, use the cd command to change directories. After running the cd command, you should notice that the text leading up to your cursor has changed. If you use the pwd command again, you can check that your directory has changed:

jane-williams@codermerlin:~$ cd myProject

jane-williams@codermerlin:~/myProject$ 

jane-williams@codermerlin:~/myProject$ pwd

/home/jane-williams/myProject 

Initializing a Git repo[edit]

Now that you have successfully navigated to the correct working directory, you can initialize your Git repo with the following command. The git init command creates an empty Git repository (or repo), and will now begin tracking changes made in the directory.

jane-williams@codermerlin:~/myProject$ git init

Adding Your First File[edit]

Since the repo is initialized, you can git add your first file. This is typically a README or an empty file that will hold your main script. If you are using Swift, it is typically called main.swift. Let's say that these files have already been created and are in your working directory:

jane-williams@codermerlin:~/myProject$ ls

README.md  main.swift 

In order to git commit or save your changes in Git, you have to git add the files first, which puts the files onto the staging area. All the files and directories on the staging area will go into the next commit. You can add files one at a time, or all together:

OPTION 1: ADD FILES ONE AT A TIME

jane-williams@codermerlin:~/myProject$ git add README.md

jane-williams@codermerlin:~/myProject$ git add main.swift

OPTION 2: ADD FILES ALL AT ONCE

jane-williams@codermerlin:~/myProject$ git add README.md main.swift

  • NOTE: the files are separated by a single whitespace.

Now that the files have been added to the staging area, you are ready to git commit.

Your First Commit (and Commit Comment!)[edit]

In order to commit your changes, use the git commit command:

jane-williams@codermerlin:~$ git commit

This command will open emacs, the text editor, in your terminal. Your cursor will appear at the top, along with two new lines and text along the following lines:

    1 | Cursor is here!

    2 |

    3 | # Please enter the commit message for your changes. Lines starting

    4 | # with '#' will be ignored, and an empty message aborts the commit.

    5 | #

    6 | # Committer: jane-williams <jane-williams@codermerlin.codermerlin.com>

    7 | #

    8 | # On branch master

    9 | #

   10 | # Initial commit

   11 | #

   12 | # Changes to be committed:

  13 | #    new file:   README.md

  14 | #    new file:   main.swift

You can then type in your commit comment in emacs:

    1 | My first commit!

    2 |

    3 | # Please enter the commit message for your changes. Lines starting

    4 | # with '#' will be ignored, and an empty message aborts the commit.

    5 | #

    6 | # Committer: jane-williams <jane-williams@codermerlin.codermerlin.com>

    7 | #

    8 | # On branch master

    9 | #

   10 | # Initial commit

   11 | #

   12 | # Changes to be committed:

  13 | #    new file:   README.md

  14 | #    new file:   main.swift

When you are satisfied with your commit comment, you can save and exit emacs:

  • Press the key sequence CONTROL-x CONTROL-c to exit, and pressy to save when prompted OR
  • Press the key sequence CONTROL-x CONTROL-s CONTROL-x CONTROL-c to save and exit.

Then, on the command line, additional text will appear. Please note that the commit comment that you added on the first line will appear.

[master (root-commit) b2e98f2] My first commit!

 2 files changed, 2 insertions(+)

 create mode 100644 README.md

 create mode 100644 main.swift

Improving Your Commit Comment[edit]

After understanding the process of writing a commit comment, it is important to determine how to write a better commit comment. As you may have guessed, you have the opportunity to write multi-line commit comments using the emacs console.

    1 | Cursor starts here!

    2 |

    3 | I can write more comments here!

    4 | I could continue on if I had more to say!

    5 |

    6 | # Please enter the commit message for your changes. Lines starting

    7 | # with '#' will be ignored, and an empty message aborts the commit.

    8 | #

    9 | # Committer: jane-williams <jane-williams@codermerlin.codermerlin.com>

   10 | #

   11 | # On branch master

   12 | #

   13 | # Initial commit

   14 | #

   15 | # Changes to be committed:

   16 | #    new file:   README.md

   17 | #    new file:   main.swift

So as not to belabor the point, countless articles have been written about the proper conventions of commit messages. The most common analogy that subject matter experts utilize is that of an email. The first line of your commit message will always appear once you save your commit. This first line, is then like the subject of an email. It is important that another coder can read this brief first line, and determine on a high-level what changes were made since the last version of the code. If the first line or "subject" is of import to the coder reading the git log then they can dig deeper into the rest of your commit comment, or the "body" of the email. As Tim Pope states in his oft-cited blogpost from 2008 on commit comments, it is important to leave an newline between the "subject" and "body" so as not to confuse certain tools or processors.[2]

The following reproduces an excerpt of Tim Pope's summary of what makes a good commit comment:[2]

    1 | Capitalized, short (50 chars or less) summary

    2 |

    3 | More detailed explanatory text, if necessary. Wrap it to about 72

    4 | characters or so. In some contexts, the first line is treated as the

    5 | subject of an email and the rest of the text as the body. The blank

    6 | line separating the summary from the body is critical (unless you omit

    7 | the body entirely); tools like rebase can get confused if you run the

    8 | two together.

There are additional conventions regarding bulleted lists (use a hanging indent, use hyphens or asterisks to denote new bullets, and separate each bullet with a newline) for more advanced commenting, but for now, it is important to focus on writing a better "subject" and relevant "body" to your commit comment.

For example, something like the below would be more informative and effective for future coders that may look into your first commit. The first commit usually will not have substantive code or changes to discuss. In fact, it is best practice to commit frequently to ensure that changes are being made in a manageable way, particularly with larger projects.

    1 | First commit, add README and main script

    2 |

    3 | Added initial files for project. main.swift will run main script, README

    4 | contains project outline.

    5 |

    6 | # Please enter the commit message for your changes. Lines starting

    7 | # with '#' will be ignored, and an empty message aborts the commit.

    8 | #

    9 | # Committer: jane-williams <jane-williams@codermerlin.codermerlin.com>

   10 | #

   11 | # On branch master

   12 | #

   13 | # Initial commit

   14 | #

   15 | # Changes to be committed:

   16 | #    new file:   README.md

   17 | #    new file:   main.swift

Future code changes and commit comment "subjects" might look something like:

  • Fixed MethodName bug (the "body" would include a description of the bug, and the solution implemented)
  • Add tests for MethodName2
  • Rework dependencies in FileName.swift and FileName2.swift

As coders get accustomed not only to writing their own code and using git, but also viewing others' code, the difference in the quality of git commit comments becomes clearer. Like any other kind of writing, practice is important, and the more a coder reads other comments and code, the better their own comment writing will become. Writing a good commit comment requires the coder to ask:

  • Who is the audience?
  • What do they need to know?
  • What is the most efficient and effective way to describe what I just changed in the code?

Using Commit Comments[edit]

When thinking about the purpose of version control, as well as documenting code, the assumption is that there will be collaborators and future coders that may need to look at and understand the code. There are different ways to look at the various commits made during the lifetime of a project. Perhaps the most succinct way is using git log, which will show all of the commits made up to the current state of the project.[3]

After the initial commit, git log would yield the following:

jane-williams@codermerlin:~/myProject$ git log

commit b2e98f28512123vsdlvbj12234e1 (HEAD -> master)

Author: jane-williams <jane-williams@codermerlin.codermerlin.com>

Date: Thu Nov 11 00:42:00 2021 -0600



  First commit, add README, and main script.



  Added initial files for project. main.py will run main script, README

  contains project outline.

Based on the above, you can see that the console included an indent on the previously written comment, so even though the console can allow for 80 characters, the 72-character suggested limit prevents anyone viewing the git log from needing to scroll left and right. If there are additional commits made to this project, the git log would show those commits as well. git log is essentially a "journal" of the version history of a code project.

From this perspective, anyone viewing the git log, whether the coder in a month or a year, or a collaborator on the project would be seeing a list of timestamps, authors, and commit comments. Clear commenting is the best way for a coder to understand what happened at each step of the code's development.

Git Commit Options: -m and --amend[edit]

The above illustrated best practices for writing quality commit comments using git commit and emacs. But git provides additional options for writing comments, and revising them. These should be used sparingly, and with best judgment based on experience, practice, and industry standards.

-m or Message Option[edit]

The following one line of code is the simplest way to commit with a comment. Modify the command git commit with the -m option and add whatever comment you would like in quotation marks after. But this command only allows short, one-line comments. In future commits that involve bug fixes, restructuring code, and more, you will want the space and a way to write more thorough notes.[4]

jane-williams@codermerlin:~$ git commit -m "My first commit!"

If you would like to write a multiline commit comment from the command line, you can also do this using the -m option twice:[4]

jane-williams@codermerlin:~$ git commit -m "Commit comment subject" -m "Commit comment body of details"

--amend Option[edit]

The --amend option allows the coder to edit and replace the most recent commit. This is not advised once the commit is pushed to remote repos or being used by other coders, as this can cause confusion. But sometimes, when working quickly, a coder can forget that they have made changes to a file or forget to add that file to the staging area before using git commit. In this case, it can be safe and easy to do the following:[5]

jane-williams@codermerlin:~$ git add ChangedFileIForgot.txt

jane-williams@codermerlin:~$ git commit --amend

If you add the --no-edit flag after --amend the original commit comment will be used for the amended commit. Note again that using git commit --amend creates a new commit that replaces the most recent commit. The prior commit will no longer be recoverable.[5]

Key Concepts[edit]

Key ConceptsKeyConceptsIcon.png
  • Big Question 1: Why bother writing quality commit comments?
    • Coders need to write quality commit comments so that their future selves and collaborators can understand how and why the code was changed.
    • Due to the format and structure of git, tools like git log rely on quality commit comments to summarize the version history of the code.
  • Big Question 2: What makes a quality commit comment?
    • A quality commit comment has to be formatted according to industry standards.
    • These standards include that each line should be no more than 72 characters long, there should be a one-line summary of the changes contained in the commit, followed by a newline, and then by a more detailed multi-line description of the commit.
  • git commit opens emacs, where the coder can write a quality, multi-line commit comment.
  • git log shows the commit history of a git repo, and each record of each commit consists of the timestamp, author, and commit comment.
  • There are additional options that alter or involve git commit comments.
    • git commit -m "commit comment" is a faster way to write commit comments, but is not always best practice.
    • git commit -m "commit comment subject" -m "commit comment body" is a faster way to write commit comments, and more expansive than the former, but is not always best practice.
    • git commit --amend allows the coder to revise and replace the most recent commit. This should be used sparingly, and not at all after a commit has been pushed to a remote repo.

References[edit]