Commit comments are an important part of Source Control that allows coders to document why and what 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
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.
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.
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:
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.
Adding Your First File
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:
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
OPTION 2: ADD FILES ALL AT ONCE
- NOTE: the files are separated by a single whitespace.
Now that the files have been added to the staging area, you are ready to
Your First Commit (and Commit Comment!)
In order to commit your changes, use the
git commit command:
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:
You can then type in your commit comment in
When you are satisfied with your commit comment, you can save and exit emacs:
- Press the key sequence - - to exit, and press to save when prompted OR
- Press the key sequence - - - - 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.
Improving Your Commit Comment
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.
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 reproduces an excerpt of Tim Pope's summary of what makes a good commit comment:
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.
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
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.
After the initial commit,
git log would yield the following:
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
The above illustrated best practices for writing quality commit comments using
git commit and
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
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.
If you would like to write a multiline commit comment from the command line, you can also do this using the
-m option twice:
--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:
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.