Skip to main content

Sending Announcements with Git Notes

Davidheadshot David Alberto

Header (15)

Hi, my name is David and I am a little obsessed with git. At Appian, we migrated from subversion in 2010 and have been using git ever since. Besides the obvious benefits like local commits and its decentralized nature, it offers interesting features like git stash, submodules, and notes.

When I learned about git notes, I thought it was interesting feature, but I could not find any actual use for it, and browsing the internet did not help with gauging its popularity. Doing code reviews via git notes could be a good use case, but tools like GitHub pull requests are an obvious winner in that regard.

Fast forward a few years, our department has grown considerably — from around 30 back in 2010, to 250 by 2018. One of the growing pains we have experienced is communicating effectively across the whole department.

Engineers on infrastructure teams often have to ask people to upgrade to a specific version of a tool, or perform an action in order to keep a working environment. Sending an email, or message in our general chat room, was no longer working, especially if people were away on vacation, or working in a different repository for an extended period of time. We generally keep our README files up to date with important information, but it can be hard for people to know when documentation has been updated.

Enter git notes.

This tool lets you attach messages to commits and other git objects. We use it to bring important tidbits of information where people are most likely to see it: the terminal. By default, git notes prints a series of hashes that might seem unusable for humans, so we wrote a small wrapper script that takes that data and turns it into meaningful information:

  • The date of the commit the note is attached to
  • The hash code for the note (useful for dismissing the note)
  • The message we want to present

Then we used git hooks to call that script. These pending notes are printed after a commit, a rebase, or a merge. The idea here is to present these reminders as often as possible and inject them on a developer’s typical workflow. Once people have taken action on a note, they can simply delete it (a local operation).

The hooks are installed via our build system, and the scripts we use look like this:

That’s pretty much it! With this tiny little tool, we now have a new way of communicating with others, and we do not have to worry about a message getting missed.


Written by

David Alberto

David is a Lead Software Engineer at Appian.