How to Install and Use git-fame in Linux to Generate Repository Contributor Statistics

Tracking individual contributions across large software repositories can quickly become overwhelming when relying solely on basic commit logs. While git log and git shortlog provide basic commit tallies, they fail to reveal the true depth of contribution, such as actual lines of code written, survivor code, and file distribution. The git-fame command-line utility fills this gap by analysing repository history to generate clean, tabular contributor statistics based on surviving code authorship, commit volume, and touched files.

Why Use git-fame for Repository Analysis?

Standard Git utilities often skew metrics in favour of developers who create frequent, tiny commits rather than those who write and maintain substantial codebases. git-fame solves this problem by evaluating multiple dimensions of codebase collaboration:

• Surviving Code Authorship: Measures lines of code that currently exist in the repository rather than deleted churn.
• Commit Frequency: Quantifies overall commit participation per author.
• File Ownership: Tallies the number of individual files containing surviving code by each contributor.
• Custom Filtering: Supports filtering by file extension, directories, date ranges, and branch references.

Installing git-fame on Linux

git-fame is a Python-based Git extension available through PyPI, Pipx, or package managers. Using pipx is strongly recommended to isolate dependencies cleanly across modern Linux distributions (such as Ubuntu 24.04 and Debian 12).

Method 1: Install via Pipx (Recommended)

Ensure pipx is installed on your Linux system, then install git-fame in an isolated environment:

# Debian / Ubuntu / Linux Mint
sudo apt update && sudo apt install -y pipx python3-pip
pipx ensurepath

# Install git-fame
pipx install git-fame

Method 2: Install via Standard Pip

On systems permitting user-level Python installs or within virtual environments, run:

pip install --user git-fame

Method 3: Arch Linux (AUR)

Arch Linux users can install git-fame directly via an AUR helper such as yay:

yay -S python-git-fame

Verify that the binary is available in your PATH:

git fame --version

Generating Basic Contributor Statistics

Navigate to any cloned Git repository on your Linux terminal and execute the command without flags:

cd ~/projects/my-repo
git fame

git-fame will scan the repository and print a formatted ASCII table similar to the following:

Statistics based on HEAD:
+-+-------------------+-------+--------+-------+
| | Author            | loc   | coms   | fil   |
+-+-------------------+-------+--------+-------+
| | Alex Morgan       | 12450 | 184    | 92    |
| | Sarah Jenkins     |  8320 | 112    | 64    |
| | David Clark       |  2150 |  45    | 18    |
+-+-------------------+-------+--------+-------+
Total commits: 341
Total LOC: 22920
Total files: 120

The table displays:

• loc: Lines of surviving code attributed to the author.
• coms: Total number of commits authored.
• fil: Total distinct files containing lines from the author.

Filtering by File Extension and Directory

In many repositories, generated lockfiles, documentation, or vendor bundles can distort contributor statistics. You can restrict the analysis to specific programming languages using the --incl (include) flag or exclude noise with --excl.

Include Specific Source Extensions

To analyse only Python and TypeScript files:

git fame --incl "\.py$|\.ts$"

Exclude Vendor and Lock Files

To eliminate generated directories and package lockfiles:

git fame --excl "node_modules|vendor|package-lock\.json|\.lock$"

Target a Specific Subdirectory

You can run git-fame against a dedicated microservice or source directory:

git fame src/backend/

Sorting and Customising Output Displays

By default, git-fame sorts contributors by lines of code (loc). You can adjust the sorting metric or alter display units to meet your reporting requirements.

Sort by Commit Count or File Distribution

To rank contributors by total commit volume rather than surviving lines:

git fame --sort coms

To sort by the number of unique files modified:

git fame --sort fil

Display Percentages Alongside Raw Tallies

Adding the --format or -c / --cost flags allows you to analyse proportions easily. You can display relative percentages using:

git fame --percentage

Exporting Contributor Data to Markdown, CSV, and JSON

For automated reporting, documentation pages, or team dashboards, git-fame provides built-in format exporters:

Export to Markdown Table

git fame --format markdown > CONTRIBUTORS.md

Export to CSV for Spreadsheet Import

git fame --format csv > repo_stats.csv

Export to JSON for Automation Scripts

git fame --format json > stats.json

Managing Author Aliases and Multiple Emails

Developers frequently commit from different machines using varied email addresses or user names. Without consolidation, git-fame will list one contributor across multiple distinct rows.

To resolve this, create or update a .mailmap file in the root of your Git repository:

# Format: Proper Name <[email protected]> Commit Name <[email protected]>
Alex Morgan <[email protected]> alexm <[email protected]>
Alex Morgan <[email protected]> Alexander Morgan <[email protected]>

Once populated, git-fame automatically respects .mailmap mappings, aggregating all historical commits and lines under the single primary author name.