git-contrib-tree 0.2.1
Analyze and visualize git repository contributions with a file tree showing top contributors.
Requires Python: >=3.6
Keywords: analysis, cli, contributions, git, tree, visualization

# 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

```bash
# 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](#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:**
```bash
uvx git-contrib-tree
```

**Install as a tool:**
```bash
uv tool install git-contrib-tree
```

**Install in a virtual environment:**
```bash
uv pip install git-contrib-tree
```

### Using pip

```bash
pip install git-contrib-tree
```

### From AUR (Recommended on Arch Linux)

```bash
# 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:

```bash
# 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:

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

## Usage

### Basic Usage

```bash
# 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

```bash
# 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

```bash
# 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

```bash
# 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

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

# Filter by single author email
git contrib-tree --email user@example.com

# Filter by multiple authors (comma-separated)
git contrib-tree --email user1@example.com,user2@example.com

# Combine with other filters
git contrib-tree --email user@example.com --since "6 months ago" --depth 2
```

### Combined Examples

```bash
# 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 user@example.com
```

## 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 <john@example.com> - 150 commits
  Jane Smith <jane@example.com> - 89 commits
  Bob Johnson <bob@example.com> - 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.
```