Git History Logbook

A comprehensive tool for exporting git commit history from multiple repositories and generating chronological logbooks with project categorization and author filtering.

Features

• Multi-repository support: Process both local paths and remote URLs (HTTPS/SSH)
• Project categorization: Group repositories by project (e.g., Neptune, Denom)
• Author filtering: Optional filtering by selected contributors
• Parallel processing: Configurable worker threads for speed
• Multiple output formats: Markdown and HTML logbooks
• Advanced filtering: Date ranges, authors, branches
• Configuration-driven: JSON config files or command-line arguments
• Automatic cleanup: Robust temporary directory management

Quick Start

1. Install Dependencies

pip install -r requirements.txt

2. Configure Repositories

Edit config.json to specify your repositories:

{
  "repositories": [
    {
      "name": "my-project",
      "url": "https://github.com/user/my-project", 
      "description": "My awesome project",
      "project": "MainProject"
    }
  ],
  "default_filters": {
    "since": "2021-01-01",
    "until": "2025-12-31"
  },
  "selected_authors": [
    "developer1",
    "developer2"
  ]
}

3. Generate Logbook

Windows (Easy):

export_history.bat

Command Line:

python git_history_logbook.py --config config.json --output my_logbook

Configuration

Repository Configuration

Each repository entry supports:

{
  "name": "repository-name",
  "url": "https://github.com/user/repo",
  "description": "Optional description",
  "project": "ProjectName"
}

Author Filtering (Optional)

Add selected_authors to filter commits by specific contributors:

{
  "selected_authors": [
    "John Doe",
    "Jane Smith",
    "developer_username"
  ]
}

Note: If selected_authors is empty or not present, all commits from all authors will be included.

Complete Configuration Example

{
  "repositories": [
    {
      "name": "neptune-webapp",
      "url": "https://github.com/user/neptune-webapp",
      "description": "Frontend application",
      "project": "Neptune"
    },
    {
      "name": "validator-scripts", 
      "url": "https://github.com/user/validator-scripts",
      "description": "Chain validation tools",
      "project": "Denom"
    }
  ],
  "default_filters": {
    "since": "2021-01-01",
    "until": "2025-12-31",
    "author": null,
    "branch": null
  },
  "selected_authors": [
    "mat",
    "biest",
    "Will Stahl",
    "Kyle King"
  ],
  "output_settings": {
    "default_format": "csv",
    "include_summary": true,
    "parallel_workers": 4
  }
}

Usage

Basic Usage

# Use config file
python git_history_logbook.py --config config.json

# Specify repositories directly
python git_history_logbook.py --repos https://github.com/user/repo1 /path/to/local/repo2

# With filters
python git_history_logbook.py --config config.json --since 2024-01-01 --author "John Doe"

Command Line Options

• --config: Configuration file (JSON)
• --repos: Repository paths or URLs (space-separated)
• --output: Base name for output files (default: commit_log)
• --csv: Save CSV file (optional)
• --since: Show commits since date (YYYY-MM-DD)
• --until: Show commits until date (YYYY-MM-DD)
• --author: Filter by author name
• --branch: Specific branch to analyze
• --workers: Number of parallel workers (default: 4)

Output Formats

Markdown Logbook

• Clean chronological format
• Organized by month and day
• Shows Project | Repository | Author for each commit
• Includes commit details and short hashes
• Perfect for documentation

HTML Logbook

• Professional web-ready format
• Modern responsive design
• Color-coded projects, repositories and authors
• Interactive and printable

CSV Export (Optional)

• Raw data for further analysis
• Includes project information
• Compatible with Excel and other tools
• All commit metadata included

Examples

Generate logbook with project categorization:

python git_history_logbook.py --config config.json --output project_history

Filter by specific date range:

python git_history_logbook.py --config config.json --since 2024-01-01 --until 2024-12-31

Save CSV and generate logbook:

python git_history_logbook.py --config config.json --csv history.csv --output project_log

Files Generated

When you run the tool, it generates timestamped files:

• commit_logbook_YYYY-MM-DD_HH-MM.md - Markdown logbook
• commit_logbook_YYYY-MM-DD_HH-MM.html - HTML logbook
• commits_YYYY-MM-DD_HH-MM.csv - CSV data (if --csv specified)

Requirements

• Python 3.7+
• Git installed and accessible from command line
• Internet connection for remote repositories
• Dependencies: pandas, openpyxl

Troubleshooting

Common Issues

1. Git not found: Ensure Git is installed and in your PATH
2. Permission errors: Run as administrator on Windows if needed
3. Network timeouts: Check internet connection for remote repos
4. Memory issues: Reduce parallel workers for large repositories
5. Author filtering: Ensure author names match exactly as they appear in git commits

Windows-Specific Notes

• Uses robust cleanup for temporary directories
• Handles Windows file permission issues
• Batch script provided for easy execution
• Local temp directories: Creates temporary git clones in current directory for better isolation

License

Apache 2.0 License - feel free to use and modify as needed.