repostat-app 2.0.0

Desktop git repository analyser and report creator.

repostat

Python3-compatible Git repository analysis html report generator with nvd3 -driven interactive visualisations of metrics. Initially, a fork of gitstats tool.

Installation

There are currently two versions maintained. Stable version is in branch v1.3.x, while development (future v2.x.x) version is on master.

Linux installation (Ubuntu 18.04 checked)

sudo pip3 install git+https://github.com/vifactor/repostat

This command installs repostat from HEAD of master branch. To install repostat at specific tag or branch, use the following syntax

sudo pip3 install git+https://github.com/vifactor/repostat@<branch|tag>

Mac OS (Catalina) installation

$ brew update
$ brew install libgit2

$ pip3 install git+https://github.com/vifactor/repostat

NOTE: Homebrew-way to install packages is slow and may break system dependencies. Please, check pygit2 installation instructions or current CI setup:

Windows installation

Check issue #57

---

Usage

repostat [--help] [--version] [--config_file CONFIG_FILE_PATH]
                 git_repository_path report_output_path

Run repostat --help for details.

Additional features

Mailmap

Starting from v1.1.2+ repostat supports git mailmap. Two things are required in order to make the feature working:

• install pygit2 v.0.28+
• create and fill .mailmap file (e.g. in the root of your repository)

Note: even Ubuntu 19.10 has libgit2 v.0.27.x in its repositories, so it means mailmap will not work there by default. Please, install newer versions (v.0.28+) of libgit2 + pygit2 to enable the feature.

Relocatable reports

By default, images, css- and js-files required to for html report rendering do not get copied to report directory. Html pages contain absolute paths to assets located in repostat installed package.

Starting from v.1.0.x, the --copy-assets command-line option forces program to copy assets to generated report and embed relative paths in html-files (see #74)

Configuration file

The report can be customized using a JSON settings file. The file is passed using the --config-file option as follows:

repostat --config-file <path_to_config.json> <repo_path> <out_path>

Configuration file might contain following fields (all are optional):

{
    "max_domains": 10,
    "max_ext_length": 10,
    "max_authors": 7,
    "max_authors_of_months": 6,
    "authors_top": 5,
    "colormap": "classic",
    "max_recent_tags": -1,
    "time_sampling": "W"
}

Detailed information about role of some fields is below:

Authors page configuration

These values are usually adjusted to accommodate projects with various number of contributors and activity levels, to avoid showing too much or too little information.

• max_domains: number of e-mail domains to show in author stats
• max_ext_length: max symbols count after . in a filename to consider substring as a file extension
• max_authors: number of authors in the "top authors" table (other authors are listed without detailed stats)
• max_authors_of_months: number of months for which "author of the month" should be displayed
• authors_top: number of authors to show for each month in the author of month/year list

Colorscheme configuration

The colors of the thread "heat maps" tables in the activity page can be customized using the "colormap" option. The allowed values are:

• classic: uses shades of red only, like gitstats. This is the default if the option is not specified.
• plasma: uses the "plasma" colormap as described here
• viridis: uses the "viridis" colormap as described here
• clrscc: uses a selection of colors from [https://clrs.cc/]

History plots sampling

is controlled by "time_sampling" field in configuration file and defines how timeseries , e.g. number of files over a repository history, are sampled. By default, weekly-sampling is used. For old repositories one might want to increase that value to month or even quarter. Accepted values for "time_sampling" are the Pandas' Offset aliases

Tags rendering

Some git repositories contain thousands of tags most of which are not worth to check. Since v.1.3.0 there is a possibility to limit the number of tags displayed in "Tags" tab of the HTML report or even hide the tab.

The feature is controlled by "max_recent_tags" field

If JSON file has following content { [...], "max_recent_tags": 8 }, the report will contain the 8 most recent tags in "Tags" page. Setting the field max_recent_tags to zero will not render "Tags" page at all. If no such field is provided in JSON settings, the report will contain a "Tags" page with all tags in the analysed repository.

How to contribute

Bug reports and feature requests as well as pull requests are welcome. Please, check the "Issues" on github to find something you would like to work on.

Debian packaging

There was some work done to prepare Debian package of repostat. The packaging code can still be found on debian/master branch in this repository. Instructions (incomplete and outdated) on how to package using gbp are in wiki.

Snap package

Incomplete and outdated snapcraft.yaml file is in snapcraft branch.