Configuration

You can create a gitstats.conf file in the current directory to customize the configuration.

  • max_domains - Maximum number of domains to display in “Commits by domain”. Default: 10.

  • max_ext_length - Maximum length of file extensions shown in statistics. Default: 10.

  • style - CSS stylesheet for the generated report. Default: gitstats.css.

  • max_authors - Maximum number of authors to list in “Authors”. Default: 20.

  • authors_top - Number of top authors to highlight. Default: 5.

  • max_tags_authors - Maximum number of authors to display per tag in “Tags” page. Set to -1 to show all authors (no limit). Default: 50.

  • commit_begin - Start of commit range (empty = include all commits). For example, 10 for last 10 commits. Default: "" (empty).

  • commit_end - End of commit range. Default: HEAD.

  • linear_linestats - Enable linear history for line statistics (1 = enabled, 0 = disabled). Default: 1.

  • project_name - Project name to display (default: repository directory name). Default: "" (empty).

  • processes - Number of parallel processes to use when gathering data, at most; never more than the machine has processors. With 1, the git commands run one at a time. Default: 8.

  • start_date - Starting date for commits, passed as –since to Git (optional). Format: YYYY-MM-DD. Default: "" (empty).

  • end_date - Ending date for commits, passed as –until to Git (optional). Format: YYYY-MM-DD. Default: "" (empty).

  • authors - Comma-separated list of authors to filter commits. Only commits from these authors will be included (uses OR logic: commits from any of the listed authors). If empty, all authors are included. Default: "" (empty).

  • exclude_exts - Comma-separated list of file extensions to exclude from line counting. If empty, no files are excluded. Files with null bytes in their content are automatically detected as binary and excluded from line counting. This detection occurs in addition to any extensions specified in exclude_exts. Default: "" (empty).

  • badge_metric - Badge written as the default badge.svg in the report output: commits, last-commit, authors, files, lines, release, active-days, summary, activity, health or ai-assisted. All of them are always pre-rendered in badges/<name>.svg regardless of this choice. Default: commits.

  • badge_label - Left-side text of the generated badges. Default: gitstats.

  • badge_color - Value-segment color of the generated badges: a shields.io color name (brightgreen, green, yellowgreen, yellow, orange, red, blue, lightgrey), a hex value like #30a14e, or any SVG color. Default: "" (gitstats brand blue).

  • badge_style - Badge style: flat (rounded corners, subtle gradient), flat-square (sharp corners), terminal (monospace and square, like the report), for-the-badge (taller, bold, uppercase) or light (white and pale blue, for white READMEs). Default: flat.

  • site_url - Public address of the report, such as https://owner.github.io/repo/. The snippets on the report’s Badges page point at it, and the run log prints the README badge. With several repositories, each report’s address is this plus its subdirectory. Same as the --site-url option. Default: "" (the Badges page reads the address from its own URL).

  • share_card - With site_url set, make every page point to share-card.png, the image shown with a link to the report where it is shared (X, Slack, LinkedIn, chat apps). gitstats writes the card as share-card.html, 1200 by 630 pixels, and leaves the PNG to whoever publishes the report, for example google-chrome --headless=new --window-size=1200,630 --screenshot=share-card.png share-card.html. Without it, the pages still carry a title and a description for such previews. Default: false.

Here is an example gitstats.conf file:

[gitstats]
max_domains = 10
max_ext_length = 10
style = gitstats.css
max_authors = 20
authors_top = 5
commit_begin = 10
commit_end = HEAD
linear_linestats = 1
project_name =
processes = 8
start_date =
end_date =
authors =
exclude_exts = png,jpg,bin,exe,dll,class,jar,zip,tar

You can also override configuration values using the -c key=value option when running the gitstats command.

For example:

gitstats . -c max_authors=10 -c authors_top=3

This command will generate a report with a maximum of 10 authors displayed and the top 3 authors shown.

Filtering examples:

# Filter commits by date range
gitstats . -c start_date=2024-01-01 -c end_date=2024-12-31

# Filter commits by specific authors
gitstats . -c authors="John Doe,Jane Smith"

# Combine multiple filters
gitstats . -c start_date=2024-01-01 -c authors="John Doe"