GitHeat

What is GitHeat?

Do you often find your self looking for a specific commit but you're unsure when it has been committed? Do you have any large git repositories that you want to find out who's contributing the most on a specifc day or month? Do you hesitate whether you should install an open-source project because you're not sure how active it is? GitHeat is developed to help you solve these problems. GitHeat will local machine to parse the git-log of your repo and allow you to navigate through an interactive heatmap in your own terminal, showing you what days are most popular, and what months are most active.

Love GitHeat? Please Tweet it, share it, or star it. I'll appreciate it! <3

How it works

Most operations you do in your Git repository only need local files and resources to operate. The entire history of your repo is stored right there on your local disk. Because of this, git doesnt need to ask a remote server to operate or to look up history to display it for you. Everything it needs is read directly from a local database on a hidden .git directory under your project root directory. In your terminal, you can try out running git log and you will see all the commits you and other contributors have made to the repository. It nice, but let us visualize it.

Now most of us are familiar with the heatmaps GitHub displays in every profile, right? Pretty cool feature. It shows you how active is a user, how many commits the pushes on a certain day or month, etc. Githeat allows you to interact and visualize a heatmap, not for a specific user, but for a specific repo. It will show you how many commits have been committed on each day during the past year, who are the top committers on a single day, what days are most active, and so on. Githeat does all of this offline and in your terminal, using just your git local database.

Installation

Install using pip:

$ pip install githeat

Or for the most up-to-date version, manual installation via setup.py.

Or to obtain the latest most-up-to-date version, clone the repo and install it from source:

$ git clone https://github.com/AmmsA/Githeat
$ cd Githeat && python setup.py install

Install for the current user:

$ python setup.py install --user

Install on your machine:

$ python setup.py install

Run the application:

$ python -m githeat --help

Run the test suite:

$ py.test test/

Examples

Interactive Examples

Want to navigate through map and interact with it? cd to your repo's root and run:

$ githeat.interactive

Use the arrows on your keyboard to navigate to a specific day. Press enter on a specific day to show the commits on that day. Press any key from 1 to 7 to show specific days. Press any key from q to ' to show specific months. Press c to change colors.

Need help? run:

$ githeat.interactive -h
usage: githeat.py [-h] [-c FILE] [--width {thick,reg,thin}]
                  [--days DAYS [DAYS ...]] [--color {grass,fire,sky}]
                  [--month-merge] [--hide-legend] [--author AUTHOR]
                  [--grep GREP] [-v]
                  [--logging {CRITICAL,ERROR,WARNING,INFO,DEBUG,NOTSET}]

githeat: Terminal Heatmap for your git repos

optional arguments:
  -h, --help            show this help message and exit
  -c FILE, --config FILE
                        Specify config file
  --width {thick,reg,thin}
                        Choose how wide you want the graph blocks to be
  --days DAYS [DAYS ...]
                        Choose what days to show. Please enter list of day
                        abbreviations or full name of week
  --color {grass,fire,sky}
                        Choose type of coloring you want for your graph
  --month-merge         Separate each month
  --hide-legend         Hide legend
  --author AUTHOR, -a AUTHOR
                        Filter heatmap by author. You can also write regex
                        here
  --grep GREP, -g GREP  Filter by keywords in commits
  -v, --version         print version and exit
  --logging {CRITICAL,ERROR,WARNING,INFO,DEBUG,NOTSET}
                        logger level

CLI Examples

Want to quickly display the heatmap? just cd to your project root (where .git is stored) and run:

$ githeat

Want to merge in the months? run:

$ githeat --month-merge

Want to separate each day block? run:

$ githeat --separate

Want to change the width of each block? choose between thin, reg, thick:

$ githeat --width {thick,reg,thin}

Want to change the color of the graph? choose between grass, sky, fire:

$ githeat --color {grass,fire,sky}

Want to show who are the top 10 most committers? run and it will parse the days for you:

$ githeat --stat --stat-number 10

Want to filter out commits by author? write regex in the author argument:

$ githeat --author="Will|Bill|"

Want to filter out commits by keywords in commit? write regex in the grep argument:

$ githeat --grep="Fix"

Have a specific YAML configuration file you want to use? pass it to the config argument:

$ githeat --config PATH_TO_CONFIG.yaml

Need help? run:

$ githeat -h
usage: githeat.py [-h] [-c FILE] [--gtype {inline,block}]
                 [--width {thick,reg,thin}] [--days DAYS [DAYS ...]]
                  [--color {grass,fire,sky}] [--stat-number STAT_NUMBER]
                  [--stat] [--separate] [--month-merge] [--author AUTHOR]
                  [--grep GREP] [-v]
                  [--logging {CRITICAL,ERROR,WARNING,INFO,DEBUG,NOTSET}]

githeat: Terminal Heatmap for your git repos

optional arguments:
  -h, --help            show this help message and exit
  -c FILE, --config FILE
                        Specify YAML config file
  --gtype {inline,block}
                        Choose how you want the graph to be displayed
  --width {thick,reg,thin}
                        Choose how wide you want the graph blocks to be
  --days DAYS [DAYS ...]
                        Choose what days to show. Please enter list of day
                        abbreviations or full name of week
  --color {grass,fire,sky}
                        Choose type of coloring you want for your graph
  --stat-number STAT_NUMBER
                        Number of top committers to show in stat
  --stat, -s            Show commits stat
  --separate, -b        Separate each day
  --month-merge         Separate each month
  --author AUTHOR, -a AUTHOR
                        Filter heatmap by author. You can also write regex
                        here
  --grep GREP, -g GREP  Filter by keywords in commits
  -v, --version         print version and exit
  --logging {CRITICAL,ERROR,WARNING,INFO,DEBUG,NOTSET}
                        logger level

Configuration

Want to change default arguments? create a .githeat dotfile in YAML format in your home directory or pass its path as an argument to --config

You can also change the colors setting. Each list in the colors list is a different coloring scheme with ansi values. Change the colors to your liking.

colors: [
    [0, 22, 28, 34, 40, 46],
    [0, 24, 31, 38, 45, 51],
    [0, 220, 214, 208, 202, 196]
    ]
width: "reg"
month_merge: false
separate: true
# author: "John"
# grep: "Fix"

Roadmap

I created this project because I wanted to quickly know how active are some open-source projects before installing them on my machine or in a project. There's still more room for improvements. I'd like to have Githeat calculate contributions statistics of specific folders or file. It will be nice to see how many times a file/folder is being changed. Maybe also integrate it with Github. I think it will be very useful to see a heatmap of not only the commits, but also issues opened and closed during development.

Maybe in future releases? Or maybe you'd like to contribute? :)

issues

Found a bug? Please report it in GitHub.

license

The MIT License (MIT)

Permission is hereby granted, free of charge, to any person obtaining a copy of this software and associated documentation files (the "Software"), to deal in the Software without restriction, including without limitation the rights to use, copy, modify, merge, publish, distribute, sublicense, and/or sell copies of the Software, and to permit persons to whom the Software is furnished to do so, subject to the following conditions:

The above copyright notice and this permission notice shall be included in all copies or substantial portions of the Software.

THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY, FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM, OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE SOFTWARE.

Interactive heatmaps for your git repositories.