Commit Comments

Within these castle walls be forged Mavens of Computer Science ...

— Merlin, The Coder

Introduction

Commit comments are an important part of Source Control that allows coders to document why changes (AKA "commits") were made. 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

Navigating to the Correct Directory

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 at 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

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

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

jane-williams@codermerlin:~/myProject$ ls

README.md  main.py 

In order to commit or save your changes in Git, you have to 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.py

OPTION 2: ADD FILES ALL AT ONCE

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

• 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!)

The following 1 line of code is the simplest way to commit with a comment. Modify the command git commit with -m 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.

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

Then, on the command line, more text will appear like such:

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

 2 files changed, 2 insertions(+)

 create mode 100644 README.md

 create mode 100644 main.py

Improving Your Commit Comment

• How to edit a commit comment

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

• How to write a good commit comment

jane-williams@codermerlin:~$ git commit -m "Subject" -m "Body of details"

Using Commit Comments

• See how important a good commit comment is?

Key Concepts

Big Picture: Why bother writing quality commit comments?

• What are commit comments AKA commit messages?
• Who uses commit comments?
• When are commit comments referenced/used?
• Why are commit comments referenced/used?
• How to write a commit comment?

Exercises

• Sample project → practice making minor edits, and writing quality commit comments

References

• "About Commits" (GitHub Docs)
• "A Note About Git Commit Messages" (2008, Tim Pope)