Installing Code Maat

Overview Link to heading

Code Maat is a forensic analysis tool for version control data, created by Adam Tornhill (author of “Your Code as a Crime Scene”). It analyzes git logs to identify hotspots, temporal coupling, code age, and other metrics. These are my notes and install instructions as I got it setup on my local machine.

Installation Link to heading

1. Install Java Link to heading

Code Maat is a Clojure application packaged as a JAR file, so it requires Java.

brew install openjdk

Add to your shell profile (~/.zshrc or ~/.bashrc):

export PATH="$(brew --prefix)/opt/openjdk/bin:$PATH"

Or create a system-wide symlink:

sudo ln -sfn $(brew --prefix)/opt/openjdk/libexec/openjdk.jdk /Library/Java/JavaVirtualMachines/openjdk.jdk

Verify installation:

java -version

2. Download Code Maat Link to heading 

mkdir -p ~/tools/code-forensics
cd ~/tools/code-forensics
curl -sL https://github.com/adamtornhill/code-maat/releases/download/v1.0.4/code-maat-1.0.4-standalone.jar -o code-maat.jar

Verify installation:

java -jar ~/tools/code-forensics/code-maat.jar -h

3. Optional: Create an alias Link to heading

Add to your shell profile:

alias code-maat="java -jar ~/tools/code-forensics/code-maat.jar"

Usage Link to heading

Step 1: Generate Git Log Link to heading

Code Maat requires a specially formatted git log. Run this in your project directory:

git log --all --numstat --date=short \
  --pretty=format:'--%h--%ad--%aN' \
  --no-renames > gitlog.txt

Step 2: Run Analysis Link to heading

All commands assume you’re in the project directory with gitlog.txt.

Change Frequency (Hotspots) Link to heading

Find files that change most often:

java -jar ~/tools/code-forensics/code-maat.jar -l gitlog.txt -c git2 -a revisions

Temporal Coupling Link to heading

Find files that change together:

java -jar ~/tools/code-forensics/code-maat.jar -l gitlog.txt -c git2 -a coupling

Authors / Ownership Link to heading

Who changed what:

java -jar ~/tools/code-forensics/code-maat.jar -l gitlog.txt -c git2 -a authors

Primary author per file:

java -jar ~/tools/code-forensics/code-maat.jar -l gitlog.txt -c git2 -a entity-ownership

Code Age Link to heading

When files were last changed:

java -jar ~/tools/code-forensics/code-maat.jar -l gitlog.txt -c git2 -a age

Code Churn Link to heading

Lines added/removed per file:

java -jar ~/tools/code-forensics/code-maat.jar -l gitlog.txt -c git2 -a abs-churn

Summary Link to heading

Repository overview:

java -jar ~/tools/code-forensics/code-maat.jar -l gitlog.txt -c git2 -a summary

Available Analyses Link to heading

Analysis Description
revisions Change frequency per file
coupling Temporal coupling between files
authors Who changed what
entity-ownership Primary author per file
entity-effort Effort distribution
age Code age
abs-churn Lines added/removed
author-churn Churn per author
communication Communication patterns
summary Repository overview

Output & Visualization Link to heading

Code Maat outputs CSV to stdout. Save to a file:

java -jar ~/tools/code-forensics/code-maat.jar -l gitlog.txt -c git2 -a revisions > revisions.csv

Tornhill provides D3.js visualization templates at: https://github.com/adamtornhill/code-maat#visualization

Quick Analysis Script Link to heading

One-liner to generate log and run all common analyses:

#!/bin/bash
# Run from your project directory

MAAT="java -jar ~/tools/code-forensics/code-maat.jar"
OUTDIR="code-forensics-output"

mkdir -p $OUTDIR

# Generate git log
git log --all --numstat --date=short \
  --pretty=format:'--%h--%ad--%aN' \
  --no-renames > $OUTDIR/gitlog.txt

# Run analyses
$MAAT -l $OUTDIR/gitlog.txt -c git2 -a revisions > $OUTDIR/revisions.csv
$MAAT -l $OUTDIR/gitlog.txt -c git2 -a coupling > $OUTDIR/coupling.csv
$MAAT -l $OUTDIR/gitlog.txt -c git2 -a authors > $OUTDIR/authors.csv
$MAAT -l $OUTDIR/gitlog.txt -c git2 -a age > $OUTDIR/age.csv
$MAAT -l $OUTDIR/gitlog.txt -c git2 -a abs-churn > $OUTDIR/churn.csv
$MAAT -l $OUTDIR/gitlog.txt -c git2 -a summary > $OUTDIR/summary.csv

echo "Results saved to $OUTDIR/"

Uninstall Link to heading

To remove Code Maat:

rm -rf ~/tools/code-forensics

To remove Java (if no longer needed):

brew uninstall openjdk