This post is part of my Git for Writers series, which I started posting as an accompaniment to my Git Started: Git for Agile Writers workshop at the STC 2015 Summit in Columbus, OH. These posts expand on some of the ideas I presented, since you can’t cram everything on such a large subject into one 45-minute workshop.

One of the most important reasons for Agile TechComm professionals to use Git is Git’s extensive set of archaeological commands. (For some more of the reasons why I think writers need Git, read this post.)

This post details some of the more useful options for the git log command. This command shows all of the log information for one or more commits. The usefulness of git log is pretty dependent on whether the various committers to a project have done their due diligence in writing commit messages, so you may find this command invaluable on some projects and useless on others.

In a perfect world where everyone follows best practices, commit messages include:

  • What the committer did.
  • Why the committer did it.
  • How the committer implemented the changes.
  • Expected behavior of the changes.
  • Testing steps to test all of the changes.

We don’t live in a perfect world, though, so sometimes commit messages in the wild are one sentence of what I call “devspeak,” and not terribly helpful.

 

For example…

The git log command shows you commit messages:

Screen Shot 2015-07-01 at 11.17.21 AM

Pretty much all of git log’s options are just filters and toggles for what parts of this information you see, and how you see it. Most of the time, when you use this command, you’re either looking for more information about a specific commit, or you’re looking through a list of recent commits to get a better idea of a project’s status.

 

Options

Like most git commands, git log includes some options that make it even more useful.

git log -n

If you’re just wanting an overview of the last few commits, you can specify a number of commits to view.

Screen Shot 2015-07-01 at 11.48.19 AM

 

 

This is useful if you’re in the habit of looking at your project in Git every day, and you just want to see what’s happened since the last time that you looked. Beware, though: if you work on a large project that requires frequent merging with a main repository, you may find yourself looking at a long list of irrelevant commits from other teams. (You can filter out merge commits by adding –no-merges to your command.)

 

git log <commit>

Adding the short-form commit ID, or SHA, narrows down the results to commits that match that SHA. (If you only want to see the closest match, add a -1 after that.)

Screen Shot 2015-07-01 at 11.01.56 AM

If you know which commit you want to take a look at, this is the best way to filter out the cruft.

 

git log -p <path>

Often, when doing git archaeology, you’re trying to track down changes in a specific file. Git blame is only really useful if you only need information about the most recent change.

Screen Shot 2015-07-01 at 11.59.07 AM

When you need to know about multiple sets of changes, git log -p lets you specify the file’s path, and returns a chronological list of the commits that touched that file. It also gives you the diff for that file for each of those commits. (Only need to know about the five most recent changes? You can add a -5 before the -p, and only receive the five most recent commits.)

 

git log –after=”date”

If you know the last date when you checked your project in Git, the –after flag will find all of the commits since then.

Screen Shot 2015-07-01 at 12.10.02 PM

 

 

Just make certain that you format the date correctly — in quotes, in YYYY-MM-DD format. You can also specify the date with a relative reference (“yesterday” or “2 weeks ago”), or add a –before date if you want to encapsulate a range of dates.

 

git shortlog

Technically speaking, this isn’t a git log option, but it’s closely-related enough that it’s worth mentioning here.

Screen Shot 2015-07-01 at 12.07.59 PM

This command returns a list of the first line of each commit message, ordered by the committer name. You can add a -n (for example, -5) to only see the most recent commits. If you don’t want to spend time reading entire commit messages, this can be helpful. This command is also often used if you need to create a changelog.

 

Go deeper

This post only scratches the surface of the options for this command, listing some of the uses that I’ve found to be most useful in an Agile environment. If you want to go into further depth, I highly recommend Pro Git (it’s free!). Of course, you can also run “git diff –help” to view the Git Manual for the command.