Thoughts on git commits

Over the last few days I read articles about git commits and commit messages here, here and here. I don’t know if the article are new or years old, but I started to reflect on my usage of git and how I create my commit messages.

First of all, there are two differences I make: personal repositories that only I work on and that I won’t share with anyone else (although they might be public on github) and professional repositories that I share with others or where I work together with a team. They have different rules in my head, and so my commit messages look a lot different. On the other hand, handling of branches is not different at all. So, let’s go over how I use branches first.

I have one rule: Use a branch for everything.

First exception to that is fixing a typo, if it’s changing just on letter.
Everything else goes into a branch first. This is useful if I decide to commit a bunch of nonsense and drop all those commits again after recognizing that I totally lost track of the goal I set out to achieve or if I want to rewrite history to please my esthetical brain. I also tend to rewrite commit messages a lot after reading them in my git log. Usually my workflow goes like this:

  • Starting working on a bugfix or feature, create a branch.
  • The initial commit has a message that follows the pattern described here.
  • Commit a bunch of stuff, sometimes WIP commits which are not a fully functional thing on their own, but just a savepoint.
  • Interactive rebase when I’m done to re-order, squash or split commits. Goal is to bring the number of commits down as much as I can without sacrificing understandability. This might end up as one big commit, but for reviews I like to keep things a bit more separated – makes it easy to follow my thoughts. I can always squash everything into a single large commit before merging.
  • Push to remote.
  • Get a review (automated for boring stuff, from a real person for the interesting things).
  • Maybe rebase on branch master to avoid garbled history on the main branch.
  • Merge with --ff-only to make sure the history is clean.

I like the branch model described in the post “A successful git branching model, but I can also work with just a master branch – as long as I can have my own feature branches on remote while working, to have the CI do all the automated checks and run my tests.

Now, let’s talk about commit messages. First my rules for professional repositories which I share and work with other people. Most important rule: The first line is a short summary of what the commit does. And I’m not talking about “Fix stuff” and the like. I also like to include a reference to the issue tracker on the first line, at the start of the message. If you generate your changelogs from git history, this will make it a lot better.

The rest of the message is a description of WHY the commit does what it does and details about the most important parts of the change. This should read like the summary at the start/end of a non-fiction book with the big picture overview. The message should also answer these questions (see this post):

  • Why is it necessary?
  • How does it address the issue?
  • What effects does the patch have?

This way your tools display nice to read, descriptive one-liners and you can read the summary chapters if you want to or if you’re looking for a specific commit.

For personal, non-shared repositories I’m less strict. If you look into the git log for this blog, for example, there is a lot of “new post” and
fix link to heroku” going on. Because it’s also not sourcecode, I don’t really care that much. Nothing breaks if I fix image URLs, no money is lost by a business and there simply isn’t much that I need to write down for myself for reference later on if I add an image to a post. ‍♂️ Most of the changes in this commits are perfectly described by a short one-liner message that says “new post”, for example when I add this article to my blog.

Ok, before I start rambling now about messy git histories on the main branch and how people don’t follow simple naming patterns on branches or how nobody seems to know how to squash commits, I’ll just stop here. There are some good articles linked, you should read them and try to write a better commit message for your next commit.


Building a Google AppEngine webapp with Python

Today I wanted to add ReCAPTCHA to one of my web applications built with NodeJS. A quick look on my heroku dashboard showed that the application wasn’t even running anymore, and a quick search through the logs showed that I was running into a quota of the connected Redis to go instance. Before doing any real work I’d have to upgrade the underlying stack, and searching for recaptcha clients for NodeJS did not bring up anything useful for me.

So, I decided to completely switch technology and rebuild the application using Google AppEngine and Python. 🙂

I closely followed the python tutorial for the first steps, creating a simple application that could store and display a single Entity of type Highlight. I then proceeded to add jinja2 templates. All of this is pretty straight forward and the application was up and running after two hours.

But then I stumbled upon a strange error: When I tried to read Entities by key from the Datastore, I couldn’t get the stored Entities back. After researching, I finally found the correct documentation and this code finally let me retrieve stored Highlight entities from the Datastore:

# get key via URL parameter 'safeKey'
# generated via myEntity.key.urlsafe()
k = ndb.Key(urlsafe = safeKey)
highlight = k.get()

Previously I used something like this:

safeKey = myEntity.key.id()

This did not return any result, although I could verify via the appengine dashboard that there really was an Entity in the Datastore with the given ID.

Anyways, you can now store syntax highlighted code at http://perfect-embassy-830.appspot.com/

Sanitize all files in a directory

Today I wanted to finally clean up several backup copies of my music.
Over the years I copied the files from device to device, moving through
multiple generations of computers. I put the music into a Jungledisk
, uploaded them to Amazon S3, copied them to my
Drobo or just moved them from one harddisk to another, bigger
harddisk. I even switched from Linux, to MacOS X, to Windows and am
on a Debian machine once again. And my next plan is to use the new
service Amazon Glacier to back it up again…

All of this moving did affect the files. The filenames are all over the
place, prefixes and funny encodings, even some of the file extensions
are no longer what they used to be.

A couple of months ago I started to write a bash script that should
help with all the confusion. It should remove all funny characters from
filenames, replace all the whitespaces with underscores and finally make
it all lowercase. That is how I like my files! 😉

Today, I gave the script another try:

(If you don’t see the code, go to github.)

You can call the script like this:

cd /path/to/your/music
./sanitize.sh . /new/path/to/your/sanitized/music/

After the script worked for several hours your files should savely sit
in the new directory, leaving the old files untouched. Then you can
start going through all the directories and remove duplicate files

You can clone the gist and modify it to your own needs. Just don’t ask
me if something went wrong. 😀

Easy code coverage reports with JMockIt

In this blog post I want to describe how I use JMockIt not only for stubs and mocks, but for easy generation of code coverage reports while developing. JMockIt is my favorite tool for unit testing, because of it’s ease of use and the many options you get out of this framework. Only recently I decided to try the code coverage report that comes with JMockIt. I was searching for an easy way to monitor my test coverage while continuing development. I didn’t want another tool or another VM running a fancy code review tool. I just wanted to see what my current test cases are covering.

My class & test

For all of you wanting to get working code I give you a code kata that I created earlier. It’s the FizzBuzz kata, and it is already prepared to run with JMockIt.

How to create reports

To create code coverage reports with JMockIt you don’t have to go to hours and hours of tool setup before you get something done. Just drop these JAR in your classpath and you’re setup to go:

  • jmockit.jar
  • jmockit-coverage.jar
  • jmockit-coverage-html[basic full].jar
  • JDK_HOME/lib/tools.jar

When you’re working inside Eclipse I recommend adding the tools.jar as a user library. See the Eclipse documentation for some help with that.

Update: With Version 0.933+ you don’t need the JDK tools.jar nor the jmockit-coverage.jar in your classpath anymore. That reduces the setup to 2 JAR files. Notice that you only need the jmockit-coverage-htmlbasic.jar> if you intend to view the report only in Eclipse. The FULL report has additional information, that might be useful to you, but I prefer fast tests and simple reports while developing. Thanks for the tips, Rogério.

Now run your JUnit test and you get a directory coverage-report with an index.html file in it. Open it in your favorite browser (or with the Eclipse/Java EE internal web browser) and you see a report.

When you dig into the FizzBuzz.java you see the details:

Do you smell something? What is that red line about? Is there code that is redundant or maybe plain wrong? Is the testcase testing the wrong things or taking false results for true? If you stumble upon something like this, this is the point where you notice that quick coverage reports are worth the setup time.

There is also a way of creating the reports from your ant script. But I’ll save that for a later blog post. If you want to try it yourself, go read the official documentation about JVM parameters.

What I think about it

This is as easy as code coverage gets: Covered lines are green, uncovered lines are red. You even get a little counter before each line telling you how many times this line was hit. Searching for performance bottlenecks? Start looking on high line counters. A whole method appearing in red? Examine the preconditions and write a test that calls that method.

Best thing on JMockIt coverage reports is: They don’t slow down your tests very much. You can just drop the JARs in your classpath and continue with your unit testing. If you want to check on your current coverage status, open the report and take a quick look. I think this is easy enough for every developer to integrate into his process. And you are already doing unit tests, right? So it shouldn’t take you more than a few mouse clicks to get a first coverage report…