Skip to main content

Desktop git repository analyser and report creator.

Project description

repostat

Build Status

Python3-compatible Git repository analyser and HTML-report generator with nvd3 -driven interactive metrics visualisations.

Initially, a fork of gitstats tool.

Installation

Starting from v2.0.0, repostat is installable from PyPi under the name repostat-app. Installation should be as simple as:

pip3 install repostat-app

Newest and older versions

  • To install a development version with newest changes from repostat's github repository, the following command may be executed:

    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>
    

NOTE: Versions prior to v2.0.0 have additional system-dependencies, e.g. gnuplot.

OS-specific requirements

Linux installation

Repostat for Ubuntu 18.04

python3-pip must be in the system and then installation via pip works fine.

Mac OS (Catalina) installation

Repostat for Mac OS

Prior to installing repostat one needs to make sure to have right version of libgit2 in the system. This can be achieved

$ brew update
$ brew install libgit2

Then, install repostat via:

$ pip3 install repostat-app

NOTE:

  1. Homebrew-way to install packages is slow and may break system dependencies.
  2. repostat's CI for OSX builds libgit2 from source.

Windows installation

Repostat for Windows

Once there is python v3.6+ in the system path, repostat can be installed via:

python -m pip install repostat-app

NOTE: On Windows 10+, symlink to general.html is not generated, when repostat launched by an unprivileged user.


Usage

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

Run repostat --help for details.

Configuration file

A 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 the 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:

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.

Additional features

Mailmap

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

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

Relocatable reports

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

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 the generated html-files.

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.

Project details


Download files

Download the file for your platform. If you're not sure which to choose, learn more about installing packages.

Source Distribution

repostat-app-2.0.2.tar.gz (30.7 kB view hashes)

Uploaded Source

Built Distribution

repostat_app-2.0.2-py3-none-any.whl (154.1 kB view hashes)

Uploaded Python 3

Supported by

AWS AWS Cloud computing and Security Sponsor Datadog Datadog Monitoring Fastly Fastly CDN Google Google Download Analytics Microsoft Microsoft PSF Sponsor Pingdom Pingdom Monitoring Sentry Sentry Error logging StatusPage StatusPage Status page