Introduction to Git Logging – InApps Technology 2022

The git distributed version control software is a software development tool that helps individuals and teams manage and maintain their source code. It is based on a snapshot model that bundles changes into commits and repositories. You can always go back and explore old configurations of code. As you might imagine, it’s definitely helpful to know when or who did a change for bug fixes, feature additions and so on.

Git has the built-in capability to give you “meta” data that is associated with each commit. This might include who authored a change, references to other commits, why was something changed, how were things affected and so on. This feature is called logging and it is the subject of today’s article.

Some Basic Git Log Options

Say you set up a git repository in the /home/rob/parts/testpart directory on your super-duper Linux notebook, using the git init command.

The repository contains a file called test1.txt, that was added and committed.

Here’s a screenshot of the file contents, using the cat command. It’s just a few lines of text.

rob% cat test1.txt

You can look at the “meta” data surrounding the creation and subsequent editing of the file using the git log command.

rob% git log

The graphic shows four commits that have occurred to the file, so far. In this example, there are six lines per commit, with a default of reverse chronological order.

The first line is the commit number (in orange text), with the branches. Next, comes the author and datelines, followed by a blank line. Finally, we see the commit comment and the separating blank line between commits.

Git log has many useful options.

The git log --stat option, gives the usual basic information along with a summary of the number of changes made between each commit, but not the specifics. You could use this option to quickly see where things were added (indicated as green plus signs) or removed (indicated as red minus signs). Changed characters show up as a green and red plus sign together. Keep in mind that for multiple git log pages, the usual vi or more-style of navigation, via the bottom of the screen “:” prompt applies.

For example, to move to the next page of the log, just hit the space bar at the “:” prompt.

To find instances of a string, at the “:” prompt, use the “/” along with the string. You’ll get a printout of the string as it shows up in the file, with a white background.

The git log -p option shows the actual changes made during an edit. Here is a section of a commit log with the text that was removed (in red) and the text added (in green).

The search “/” command-line switch works with both the –stat and -p options.

You might want to just see the last few commits, instead of the whole list. Use the -n option with the number of commits. For example -n 2 would print out the latest two commits. Make sure your terminal is large enough to see the number you’d like or it will automatically go into “:” paging mode.

rob% git log -n 2

Let’s Talk about Git Commit Messages

Commit messages are another awesome feature of git. They help you add descriptive text to each commit so a future you or team member can figure out what, why, when and how a change was made to the code. Best of all is that it is simple to use and is seamlessly integrated right into the git log. A basic git commit, with its associated message looks like the following.

%rob git commit -m "This is a possible git commit message"

The messages show up in the git log printouts.

Writing good git commit messages is a whole topic in itself and you can certainly go much further than a basic message. Lots of companies apply conventions to their commit messages, so you might want to check on those, if you are new to using git in your organization.

One general convention is known as “50/72” formatting. Here, you summarize the git commit using a title of 50 characters or less, then a blank line, followed by a more detailed description of the commit (code change) of 72 characters or less. The formatting minimizes problems associated with line wraps that make the text hard to read in external git applications or on small devices, such as phone screens. I don’t use my Samsung S8+ for reading git logs, although I suppose some people might. Just stay under these line lengths and you should be good.

You aren’t limited to just two lines either. Use multiple “-m” in the git commit to separate them into paragraphs, with a blank line between each one.

Some people also use much longer messages. This is possible using an editor such as vi. Using “git commit” without a message will put you into your editor. Set it up with the following.

rob% git config --global core.editor vi

If you want to other editors such as nano, etc., substitute in your editor program of choice in place of vi in the git config command.

Another convention you might use is a keyword at the beginning of your message to indicate the type of change made. Organizations usually standardize on this word list and might include terms like fix, refactor, test, docs or chore. Lots of people follow the commit type with a semicolon and a space before the summary text. Here’s a silly physical computing example.

rob% git commit -m "test: adj servo travel var - robot head rotation"

Using a keyword lets you easily distinguish the purpose of a commit, once you get used to using them.

git commit messages are a whole subject on their own and there are many opinions surrounding the subject. Suffice it to say that they are very useful, especially for maintenance and troubleshooting, when revisiting a project a year from now and trying to figure out why you changed your code, way back when.

Wrap up

Git log is an important command in your software development toolkit. The commit history is neatly arranged and there are many options to fine-tune the exact information you want to see. Writing good log messages, consistently, will make life easier as you develop your projects.

Contact Rob “drtorq” Reilly for consultation, speaking engagements and commissioned projects at [email protected] or 407-718-3274.

InApps Technology is a wholly owned subsidiary of Insight Partners, an investor in the following companies mentioned in this article: Torq.