gitstats

Generate statistics for a local repository

$ gitstats [path/to/git_repo/.git] [path/to/output_folder]

$ [Invoke-Item|open|xdg-open] [path/to/output_folder/index.html]

gitstats [OPTIONS] <repository_path> [<output_directory>]

<repository_path>
    The path to the Git repository to be analyzed. This is a mandatory argument.

<output_directory>
    Optional. The directory where the generated HTML reports will be stored. If omitted, defaults to ./gitstats in the current working directory.

--full
    Generates statistics for the entire history of the repository, rather than just the last year (which is often the default if not specified).

--full-history
    Similar to --full, ensures all commits from the repository's beginning are included in the analysis.

--authors-top=<num>
    Limits the author statistics to the top <num> contributors (default: 5).

--max-authors=<num>
    Sets the maximum number of authors to display on graphs (default: 20). If more authors exist, they are grouped as 'Other'.

--style=<css_file>
    Specifies a custom CSS file to use for styling the generated HTML reports, overriding the default stylesheet.

--since=<date>
    Only processes commits made since the specified <date> (e.g., '2023-01-01' or '2 weeks ago').

--until=<date>
    Only processes commits made until the specified <date> (e.g., 'yesterday' or '2024-01-01').

--pretty-names
    Attempts to use more readable names for authors (e.g., 'John Doe' instead of 'john.doe@example.com').

--exclude=<list>
    A comma-separated list of file paths or directories to exclude from the analysis.

--list-languages
    Lists all supported programming languages that gitstats can analyze and then exits.

--version
    Displays the program's version number and exits.

--help
    Displays the help message and exits.

gitstats is a Python-based command-line tool designed to generate detailed statistics from a Git repository.

It scans the repository's commit history to gather various metrics, such as commit activity (daily, hourly, weekly, monthly), author contributions, file types, lines of code added/removed, and commit message details. The collected data is then processed and rendered into a set of interactive HTML files, complete with graphs generated by Gnuplot.

This allows developers and project managers to gain deep insights into the project's development trends, team activity, code evolution, and overall project health. The generated reports are self-contained and can be easily viewed in any web browser, making them convenient for sharing and analysis.

Analyzing very large or old Git repositories can be resource-intensive and take a significant amount of time.

Accuracy of statistics depends on the consistency of author names and emails within the Git history; inconsistent data might lead to authors being counted separately even if they are the same person (though --avoid-email-clones helps mitigate this).

gitstats requires Python (version 2.7+ or 3.x), the Git command-line tool, and Gnuplot to generate the visual graphs within the HTML reports. These must be installed and accessible in the system's PATH.

The command generates a directory containing an index.html file along with subdirectories for images (graphs) and CSS. The index.html serves as the main entry point to navigate through various statistical reports like commit activity, author activity, file statistics, and more.

gitstats was initially developed by Ahti Heinla and released around 2008. It has since been maintained and improved by various contributors, primarily hosted on GitHub. Its purpose has consistently been to provide a visual, accessible, and comprehensive overview of Git repository activity, leveraging Python for data processing and Gnuplot for graphical representation.

git(1), git-log(1), git-blame(1), cloc(1)