Heatmapper is a simple command line utility to output github style heatmaps on the command line.
It's specifically focused on just the heatmap, and intended to be leveraged by other programs. Either via the command line OR via your favorite language's ability to leverage C libraries (see below).
If you want to generate a command line heatmap with your GitHub information I recommend you check out these two projects
- Heatwave by James Stoup (Python)
- Git Stats by Ionică Bizău (JavaScript)
Heatmapper is written in Chicken Scheme
You can install that with brew install chicken-scheme
if
you're on macOS or Linux, otherwise follow the instructions on their
site.
Once you've gotten that installed:
cd src
# install the required libraries
./install_chicken_eggs.sh
./build.sh
That's it. You should now have a heatmapper
executable in
the same directory.
There are a couple test files in misc:
numbers.txt
random_numbers.txt
Try running cat ../misc/random_numbers.txt | ./heatmapper
just to make sure everything's working.
If everything looks good, copy that somewhere in your PATH and you're good to go.
Just pipe some data into it and it'll generate at heatmap 80 columns wide and 7 rows tall.
❯ ./heatmapper --help
Usage: piped data | heatmapper heatmapper [options...]
Supported color schemes: github, darkdub, bluehub, wistia
-c, --columns=ARG max number of columns [default: 80]
-r, --rows=ARG max number of rows [default: 7]
-s, --scheme=ARG color scheme [default: github]
-h, --help Display this text
Report bugs to https://github.com/masukomi/heatmapper/issues
The data fills from from the top left corner down, then moves one column to the right, and fills down again. It stops when it runs out of data or hits the maximum number of columns. Unfinished rows will be filled out with zero values.
A good way to have it always use your current terminal width (in bash / zsh) is to use tput
as follows:
cat numbers.txt | heatmapper --columns $(tput cols)
If you want to use this in something that generates HTML you could use oho to convert the output to HTML.
Adding a color scheme is pretty easy, even if you don't know Chicken
Scheme. You'll need a palette of 5 colors. Get their RGB values, then
open up the src/heatmap.scm
file.
The first define
in that file is setting up the color
schemes. Just replicate what's in the existing ones, change the color
numbers, and give it a new name. Note that the colors are ordered from
lightest to darkest.
The color name comments are entirely optional, but nice to have. :D
Chicken Scheme compiles to C.
You can actually generate the C source files and headers for use in other projects. I've specifically designed this so that you can have just the core library without the command line handling stuff.
The file you want is src/heatmap.scm
Follow the instructions here to generate the C files and headers.
Before I ported this to Chicken Scheme I prototyped the idea with a quick and dirty ruby script. You can find it in misc/ruby_prototype.rb
If you do use this in something, please Let me know on Mastodon.
If you've got an issue, please file a ticket here on GitHub.
This code is distributed under the AGPL license. See the LICENSE
file for more details.
If you need to incorporate this into a commercial product I'm happy to give you a difference license in exchange for money. ;)