git-contrib-tree 0.1.0

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
• Filter by date range (--since/--until)
• Filter by contributor email(s)
• List all contributor emails
• Control tree depth (useful for large repositories)
• Analyze specific subtrees within a repository

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)

uv pip install git-contrib-tree

Using pip

pip install git-contrib-tree

Arch Linux (AUR)

# 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

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 .

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 https://gitlab.com/wykwit/git-contrib-tree/-/raw/main/git-contrib-tree
chmod +x git-contrib-tree

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

# Or with Python
python3 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

Quick Start

# Analyze current directory
git contrib-tree

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

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

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

Usage

Basic Usage

# Analyze current directory
git contrib-tree

# Analyze specific repository
git contrib-tree --repo /path/to/repo

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 Path

# Analyze only the src directory
git contrib-tree --path src

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

# Analyze specific file
git contrib-tree --path README.md --depth 0

Date Filtering

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

# Analyze last 6 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 specific repo and time period
git contrib-tree --repo ~/projects/myapp --since "2024-01-01" --depth 3

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

# See specific author's contributions in a directory
git contrib-tree --path 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
--repo PATH	.	Path to git repository
--depth N	-1	Maximum tree depth to display (0=project only, -1=unlimited)
--path PATH	None	Analyze only this path within the repository
--since DATE	None	Show commits after this date
--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 you're in a git repository or use --repo to specify the path
• Run git status to verify the directory is a git repository

No commits shown:

• Check your date filters (--since, --until) - they might be excluding all commits
• 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.