Python3-compatible Git repository analyser and HTML-report generator with nvd3 -driven interactive metrics visualisations.
May not work with Python 3.9+! See vifactor#198
Initially, a fork of gitstats tool.
Check how a repostat's report looks like by going to:
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
-
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
.
python3-pip
must be in the system and then installation via pip
works fine.
Prior to installing repostat one needs to make sure to have right version of libgit2 in the system. This can be achieved
- following pygit2 installation instructions
- (not recommended) installing it via Homebrew
$ brew update
$ brew install libgit2
Then, install repostat via:
$ pip3 install repostat-app
NOTE:
- Homebrew-way to install packages is slow and may break system dependencies.
- repostat's CI for OSX builds libgit2 from source.
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.
repostat [--help] [--version] [--config_file CONFIG_FILE_PATH]
git_repository_path report_output_path
Run repostat --help
for details.
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_authors": 7,
"max_plot_authors_count": 10,
"max_authors_of_months": 6,
"authors_top": 5,
"colormap": "classic",
"max_recent_tags": -1,
"orphaned_extension_count": 2,
"time_sampling": "W"
}
Detailed information about role of the fields is below.
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 statsmax_authors
: number of authors in the "top authors" table (other authors are listed without detailed stats)max_plot_authors_count
: number of authors to include in plots in "Authors"-page (rest of the authors will be grouped as "Others").max_authors_of_months
: number of months for which "author of the month" should be displayedauthors_top
: number of authors to show for each month/year in the author of month/year listorphaned_extension_count
: max file extension count to be considered asorphaned
and displayed in report in the corresponding category (default: 0, i.e. all extensions are displayed)
The colors of the thread "heat maps" tables in the activity page can be customized using the "colormap" option. The allowed values are:
classic
: (default) uses shades of red only, like gitstatsplasma
: uses the "plasma" colormapviridis
: uses the "viridis" colormapclrscc
: uses a selection of colors from https://clrs.cc/
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
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.
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)
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.
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.