Warning herdstat is work in progress and neither feature complete nor tested thoroughly.

herdstat is a tool for analyzing and visualizing metrics of Open Source projects hosted on GitHub. As of today its functionality is limited to generate GitHub-style contribution graphs for individual repositories or whole GitHub organisations.

herdstat is composed of the words herd, which means a group of people who usually have a common bond, and stat, which is a well-known Linux command line utility that displays detailed information about files. So replacing file with open source community (= herd) does the trick in understanding why we have chosen that name.

herdstat has an installer script that will download and install it locally.

You can fetch the script and execute it locally. It's well documented so that you can read through it and understand what it is doing before you run it.

BRANCH_OR_TAG=main
curl -fsSL "https://raw.githubusercontent.com/herdstat/herdstat/${BRANCH_OR_TAG}/scripts/get-herdstat.sh"
chmod 700 get-herdstat.sh
./get-herdstat.sh

For available options run

./get-herdstat.sh --help

If you want to live on the edge, you can run one of the following commands depending on the shell you are using:

BRANCH_OR_TAG=main
curl "https://raw.githubusercontent.com/herdstat/herdstat/${BRANCH_OR_TAG}/scripts/get-herdstat.sh" | bash

BRANCH_OR_TAG=main
curl "https://raw.githubusercontent.com/herdstat/herdstat/${BRANCH_OR_TAG}/scripts/get-herdstat.sh" | zsh

You can execute herdstat using Docker via

docker run herdstat/herdstat /herdstat -r herdstat contribution-graph

Alternatively, you can use the herdstat GitHub action.

herdstat can be configured either by providing arguments to the CLI or by means of a configuration file via the global --config CLI flag. The list of available configuration options is summarized in the following table:

You can build herdstat by invoking

git clone https://github.com/herdstat/herdstat.git
cd herdstat
go build

Instead of using golang tooling, you can build herdstat from its sources using Docker. To build the image invoke

docker build . -t herdstat-dev

You can execute herdstat, e.g., on the herdstat GitHub organization, using

docker rm herdstat-dev || true
docker run --name herdstat-dev -it herdstat-dev /herdstat -r herdstat contribution-graph

To extract the generated contribution graph from the Docker container invoke

docker cp $(docker ps -aqf "name=herdstat-dev"):/contribution-graph.svg .

To remote debug herdstat build the image with the ENV build variable set to debug

docker build  -t herdstat-dev --build-arg ENV=debug .

and start a container using

docker rm herdstat-dev || true
docker run --name herdstat-dev --security-opt="apparmor=unconfined" \
  --cap-add=SYS_PTRACE -p 40000:40000 -it herdstat-dev \
  /dlv --listen=:40000 --headless=true --api-version=2 --accept-multiclient exec /herdstat -- --verbose -r herdstat contribution-graph

You can then connect via your IDE or from the commandline on port 40000.