Making Sense of Git Log files

Git logs allow you to review and read a his­to­ry of every­thing that hap­pened to a repos­i­to­ry. The his­to­ry is built using git-log, a sim­ple tool with a ton of options for dis­play­ing revi­sion history. 

What is a Git Log? #

A Git log is a run­ning record of com­mits. A full log has the fol­low­ing pieces:

  • A com­mit hash (SHA1 40 char­ac­ter check­sum of the com­mit contents).
  • Com­mit Author meta­da­ta: The name and email address of the author of the commit.
  • Com­mit Date meta­da­ta: A date time­stamp for the time of the commit
  • Com­mit title/​message: The overview of the com­mit as writ­ten in the com­mit message.

A Typ­i­cal Git Log #

Git logs can be what­ev­er you want them to be. git-log offers dozens and dozens of options but let’s start with the simplest. 

$ git log

This out­puts the most basic log:

  commit 98aa8d722bdecc4e56156cfe1a793a4d16848eb8
  Author: Ryan Irelan <[email protected]>
  Date:   Sat Jan 10 23:26:40 2015 -0600
  Adding in new homepage
  Includes the assets needed for Foundation
  commit dd8d6f587fa24327d5f5afd6fa8c3e604189c8d4
  Author: Ryan Irelan <[email protected]>
  Date:   Tue Jan 6 20:07:17 2015 -0600
  added origination declaration at bottom of RSS feed

This is a snip­pet of the log, show­ing two com­mits. We have a com­mit SHA1 hash, the author, the date, and the com­mit mes­sage, explain­ing what hap­pened in the commit. 

This lay­out is the default look of the log. Git has some­thing called Com­mit Lim­it­ing to make it eas­i­er to nar­row down hun­dreds or thou­sands of com­mits to the ones you want to review.

Direc­to­ry Restrict­ed Log #

The default log is great for grab­bing a quick look at what just hap­pened in the repos­i­to­ry. But it takes up a lot space and you can only see a hand­ful of com­mits at once.

When I’m devel­op­ing a project, I some­times only want to know what hap­pened in a spe­cif­ic direc­to­ry. Let’s say I’m work­ing on some CSS or Sass for a web-based project and only want to know about changes in my Sass direc­to­ry. I can get much more spe­cif­ic with git-log and restrict it only to a spe­cif­ic directory.

git log scss

This will only return com­mits that had changes in the scss directory.

Log by branch #

We can use a sim­i­lar syn­tax as direc­to­ry restric­tion and build a log for just one branch. We only need to spec­i­fy the branch we want to see.

git log develop

We can clean that up a lit­tle by remov­ing any merge com­mits (which can bulk up the log if there are a lot of merges, like there would be a develop branch.

git log develop --no-merges

On larg­er projects, with mul­ti­ple devel­op­ers work­ing and com­mit­ting changes, the log can get unwieldy very quick­ly. We just learned how to restrict by direc­to­ry, but let’s restrict by time.

Time-restrict­ed log #

Noth­ing beats a sense of accom­plish­ment at the end of the day like look­ing back at every­thing you did. Git-log let’s us review our work for the day by restrict­ing to just com­mits we made today.

$ git log --since=8am

This will out­put all of the com­mits made by every­one since 8 AM this morn­ing. That’s great for review­ing what the entire team has accom­plished but I’d like to see what I have accom­plished. Let’s make it a bit more specific.

git log --since=8am --author=ryan

Ah, that’s much better!

In the morn­ing, before my cof­fee real­ly starts to kick in, I like to review the work I did the pre­vi­ous day on a spe­cif­ic project. For this we can use a mod­i­fied ver­sion of the last git log com­mand to show only what we worked on yesterday.

git log --since=yesterday --author=ryan

That works if we haven’t made any com­mits yet today. 

To review a project’s work for the entire team over the course of a month, we can use --before and --after again and just leave off the the --author flag.

$ git log --before={2015-01-01} --after={2014-11-30}

Now we’re build­ing the log using only com­mits that were cre­at­ed after Novem­ber 30, 2014 and before Jan­u­ary 1, 2015. That iso­lates the time peri­od to only the month of December.

We can use the --before and --after flags to han­dle pret­ty much any time peri­od we want, which makes this a pow­er­ful way to build a com­mit log that works for what­ev­er we need.

Search­ing Com­mits to Build a Log #

We can also lim­it the log that is out­putted by search terms. To do this we use the --grep option and pass in a term or reg­u­lar expression. 

$ git log --grep="homepage"

This will return a log with com­mits that only ref­er­ence the word home­page” in the com­mit message.

See­ing Diffs in the Log #

When we get our log out­put very spe­cif­ic we may want to expand the amount of infor­ma­tion that we’re show­ing there so we the com­mits we’re view­ing are as help­ful as possible.

We do that using the -p option to show diffs of the changed files.

git log -p

If we keep our com­mits as atom­ic as pos­si­ble then this diff view should be fair­ly easy to manage. 

Let’s put togeth­er every­thing we’ve learned up to this point with spec­i­fy­ing how our log outputs. 

$ git log -p --grep="homepage" --before={2015-01-01} --after={2014-11-30} 

This git log com­mand shows the full diff (the -p), searched the com­mit mes­sages for the word home­page”, only uses com­mits in the month of Decem­ber 2014, and they’re only authored by me. 

Git Log with Graph #

I like to see a quick glance at the git log that shows me the struc­tur­al his­to­ry of the repos­i­to­ry. I want to see where branch­ing and merg­ing happened. 

Git offers a sim­ple way: the --graph option.

$ git log --graph

This will draw a text-based graph of the com­mit his­to­ry. Along the left side of the out­put you should see a series of dash­es. If you have branch­es and merges in the his­to­ry of your repos­i­to­ry then you should see those indicated.

One note: if you’re run­ning the com­mand in a small ter­mi­nal win­dow, you might want to expand it to see the graph appear properly.