Commit Comments
Introduction[edit]
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[edit]
[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 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[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 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!)[edit]
In order to commit your changes, use the 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.py
15 | #
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.py
15 | #
When you are satisfied with your commit comment, you can save and exit emacs based on your OS:
- Hit Esc and typing :wq OR
- Hit Ctrl+X+Ctrl+C and typing y
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.py
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.py
18 | #
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.
The following is an excerpt of Tim Pope's summary of what makes a good commit comment (Tim Pope, 2008):
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.
9 |
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.py 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.py
18 | #
Future code changes and commit comment "subjects" might like 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.py and FileName2.py
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]
- See how important a good commit comment is?
Key Concepts[edit]
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?
ADDITIONAL NOTES[edit]
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!"
- How to amend a commit comment -- do so sparingly
jane-williams@codermerlin:~$ git commit --amend
- How to write a good commit comment
jane-williams@codermerlin:~$ git commit -m "Subject" -m "Body of details"
Exercises[edit]
- Sample project → practice making minor edits, and writing quality commit comments
References[edit]
- "About Commits" (GitHub Docs)
- "A Note About Git Commit Messages" (2008, Tim Pope)
- "Rewriting History: Git commit --amend and other ways to rewrite history" (Atlassian BitBucket)
