git-punchcard 1.3.0

punchcard generator for git commit frequencies

Simple git punchcard utility, inspired by git-punchcard-plot but rewritten for python3 with matplotlib.

Installation

The pragmatic way: The script can be obtained from PyPI:

pip install --user git-punchcard

Also, make sure that ~/.local/bin is in $PATH. If it is not there, add the following lines to .bashrc or .zshrc:

PATH=$PATH:$HOME/.local/bin

The elegant way: Get pipx and then run pipx install git-punchcard to install into an isolated environment.

The crude way: Alternatively, simply drop the git_punchcard.py script into ~/.local/bin, rename to git-punchcard and add the folder to PATH.

Usage

The syntax of the command is as follows:

git punchcard [options] [log options] [revision range] [-- pathes]

To get a list of available options, type:

git punchcard -h            # for our own options

git help log                # for possible git log options

git help gitrevisions       # for revision range

The most important options are:

Show a github-like punchcard plot with grid:

git punchcard --grid

By default, the author’s local timezone is used for the plot. In order to use a fixed timezone for all commits, you have to specify a --timezone argument, e.g.:

git punchcard --timezone CET

Set the directory of the git repository as follows:

git punchcard -C /path/to/repo

Advanced examples

You can pass additional options understood by git log. This can for example be used to restrict the range of commits and/or limit to commits performed by a certain author:

# include only commits by specific author:
git punchcard --author=myself

# consider only only the 20 commits:
git punchcard master~20..master

# commits within a certain time frame:
git punchcard --since="1 year ago" --until=now

# show at which times a certain file/folder is usually edited:
git punchcard --follow -- src
git punchcard --follow -- docs

# show at which times, people like to merge:
git punchcard --merges

You can even to restrict to certain pathes within the git repository as follows:

git punchcard -- README.rst

Track evolution of commit activity over the years:

for year in {2016..2019}; do
    git punchcard -o $year.png --title $year \
        --since 1.1.$year --until 31.12.$year
done