git-contrib-tree 0.2.1

Analyze and visualize git repository contributions with a file tree showing top contributors.

git-contrib-tree

A Python tool to analyze and visualize git repository contributions by displaying a file tree with the top 3 contributors for each file and directory.

Note: This project was created with the assistance of Large Language Models (LLMs) for code generation, optimization, and documentation.

Features

• Display repository file tree with top contributors per file
• Show top 3 contributors for directories (aggregated from all files within)
• Show commit counts alongside contributor names
• Default time filter: analyzes last 3 months of contributions
• Filter by custom date range (--since/--until) or use -1 for all history
• Filter by contributor email(s)
• List all contributor emails
• Control tree depth (useful for large repositories)
• Simple path argument: accepts absolute repo paths or relative paths within repo

Quick Start

# Analyze current directory (defaults to last 3 months)
git contrib-tree

# Show project-level overview
git contrib-tree --depth 0

# See who worked on what in the last 6 months
git contrib-tree --since "6 months ago"

# List all contributors
git contrib-tree --list-emails

See Usage section for more detailed examples and options.

Requirements

• Python 3.6+
• Git installed and accessible in PATH
• A git repository to analyze

No external dependencies required - uses only Python standard library and git.

Installation

Using uv (Recommended)

Run without installing:

uvx git-contrib-tree

Install as a tool:

uv tool install git-contrib-tree

Install in a virtual environment:

uv pip install git-contrib-tree

Using pip

pip install git-contrib-tree

From AUR (Recommended on Arch Linux)

# Using an AUR helper
paru -S git-contrib-tree

This installs the git-contrib-tree command, making it available as both:

• A standalone command: git-contrib-tree
• A git subcommand: git contrib-tree

Standalone Script

The git-contrib-tree script is a self-contained Python file with no external dependencies. You can use it directly without installing the package:

# Download the script
curl -o git-contrib-tree https://gitlab.com/wykwit/git-contrib-tree/-/raw/main/git-contrib-tree.py
chmod +x git-contrib-tree

# Run it directly
./git-contrib-tree --help

This is useful for:

• One-off usage without installation
• Including in other projects or scripts
• Running on systems where you can't install packages

Development Installation

For development, clone the repository and install in editable mode:

git clone https://gitlab.com/wykwit/git-contrib-tree.git
cd git-contrib-tree
uv pip install -e .

Usage

Basic Usage

# Analyze current directory (default: last 3 months)
git contrib-tree

# Analyze specific directory (relative to current location)
git contrib-tree src

# Analyze different repository (absolute path)
git contrib-tree /path/to/repo

# Analyze specific file
git contrib-tree README.md

Depth Control

# Show only project-level contributors
git contrib-tree --depth 0

# Show root level only
git contrib-tree --depth 1

# Show files up to depth 2
git contrib-tree --depth 2

# Show all files (default)
git contrib-tree --depth -1

Note: Depth controls what is displayed, not what is analyzed. Directory summaries always include all files within them, even if those files are not shown due to depth limits.

Analyze Specific Paths

# Analyze the src directory (relative to current location)
git contrib-tree src

# Analyze src/models with depth 1
git contrib-tree src/models --depth 1

# Analyze specific file with project-level view
git contrib-tree README.md --depth 0

# Analyze different repository
git contrib-tree /absolute/path/to/other/repo

# Combine with date filter
git contrib-tree src --since "6 months ago"

Date Filtering

# Analyze all history
git contrib-tree --since -1

# Analyze contributions from specific date
git contrib-tree --since "2024-01-01"

# Analyze last 6 months (default is 3 months)
git contrib-tree --since "6 months ago"

# Analyze until specific date
git contrib-tree --until "2024-12-31"

# Analyze specific date range
git contrib-tree --since "2024-01-01" --until "2024-12-31"

Supported date formats:

• Specific dates: "2024-01-01", "Jan 1 2024"
• Relative dates: "6 months ago", "1 year ago", "2 weeks ago"
• ISO format: "2024-01-01T00:00:00"

Author Filtering

# List all contributor emails
git contrib-tree --list-emails

# Filter by single author email
git contrib-tree --email [e-mail]

# Filter by multiple authors (comma-separated)
git contrib-tree --email [e-mail],[e-mail]

# Combine with other filters
git contrib-tree --email [e-mail] --since "6 months ago" --depth 2

Combined Examples

# Analyze last year with depth 2
git contrib-tree --since "1 year ago" --depth 2

# Analyze different repository and time period
git contrib-tree ~/projects/myapp --since "2024-01-01" --depth 3

# Analyze src directory from last 6 months
git contrib-tree src --since "6 months ago" --depth 2

# See specific author's contributions in a directory
git contrib-tree src --email [e-mail]

Output Examples

Project Level (--depth 0)

Project: my-repository
  Top contributors: John Doe (150), Jane Smith (89), Bob Johnson (45)

Tree View (Full Depth)

Repository: my-repository

├── README.md - John Doe (5), Jane Smith (2)
├── src/ - John Doe (48), Jane Smith (23), Bob Johnson (10)
│   ├── main.py - John Doe (25), Bob Johnson (10), Jane Smith (3)
│   ├── utils.py - Jane Smith (15), John Doe (8)
│   └── models/ - Bob Johnson (20), John Doe (15), Jane Smith (5)
│       └── user.py - Bob Johnson (20), John Doe (5)
└── tests/ - Jane Smith (12), John Doe (8), Bob Johnson (2)
    └── test_main.py - Jane Smith (12), John Doe (8), Bob Johnson (2)

Tree View with Depth Limit (--depth 1)

Repository: my-repository

├── README.md - John Doe (5), Jane Smith (2)
├── src/ - John Doe (48), Jane Smith (23), Bob Johnson (10)
└── tests/ - Jane Smith (12), John Doe (8), Bob Johnson (2)

List Contributors (--list-emails)

Contributors:
  John Doe <[e-mail]> - 150 commits
  Jane Smith <[e-mail]> - 89 commits
  Bob Johnson <[e-mail]> - 45 commits

Note:

• Directory summaries show aggregated contributions from all files within that directory and its subdirectories
• Even when depth is limited, directory summaries include contributions from all nested files
• Files/directories with no contributions from filtered authors are hidden when using --email

Command Line Options

Option	Default	Description
path	.	Path to analyze (absolute repo path or relative path within repo)
--depth N	-1	Maximum tree depth to display (0=project only, -1=unlimited)
--since DATE	3 months ago	Show commits after this date (use -1 for all history)
--until DATE	None	Show commits before this date
--email EMAILS	None	Filter by author email(s), comma-separated
--list-emails	False	List all contributor emails and exit

How It Works

The tool analyzes git history efficiently using batch operations:

1. File Discovery: Uses git ls-files to get all tracked files (optionally filtered by path)
2. Tree Building: Builds a complete file tree structure in memory
3. Batch Loading: Runs a single git log --name-only command to get all commits and affected files
4. Efficient Parsing: Parses the output to build contributor data for all files simultaneously
5. Bottom-Up Aggregation: Calculates directory contributors by aggregating from files within
6. Smart Display: Displays the tree up to the specified depth limit while maintaining accurate summaries

Use Cases

• Code review: Identify file owners and subject matter experts
• Team analysis: Understand contribution patterns across your codebase
• Onboarding: Help new team members identify who to ask about specific files
• Project planning: Visualize which parts of the codebase have concentrated knowledge
• Historical analysis: Track how contributions have changed over time using date filters
• Individual tracking: See what files a specific contributor has worked on
• Refactoring: Identify highly-modified files that might benefit from cleanup

Troubleshooting

"Not a git repository" error:

• Ensure the path you specified is inside a git repository
• Run git status to verify the directory is a git repository
• If using a relative path, make sure you're starting from a location within the git repo

No commits shown:

• Check your date filters (--since, --until) - by default, only the last 3 months are shown
• Verify files exist in git: git ls-files
• Ensure the specified path exists in the repository
• Check that the --email filter matches actual contributor emails (use --list-emails)

Unexpected contributor names:

• Git uses the name from commits, which may vary if contributors use different names
• Check commit history: git log --format=%aN | sort -u
• Use --list-emails to see all contributor emails and their associated names

License

This project is dual-licensed under the MIT License and WTFPL.

MIT License

Copyright (c) 2025 wykwit

Permission is hereby granted, free of charge, to any person obtaining a copy
of this software and associated documentation files (the "Software"), to deal
in the Software without restriction, including without limitation the rights
to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
copies of the Software, and to permit persons to whom the Software is
furnished to do so, subject to the following conditions:

The above copyright notice and this permission notice shall be included in all
copies or substantial portions of the Software.

THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
SOFTWARE.