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:

.. code-block:: ini

   [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:

.. code-block:: bash

   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:

.. code-block:: bash

   # 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"