# git-history-extraction
A tool to extract and filter git commit history, making it easy to pipe to AI tools for changelog generation and summaries.
## Features
- Extract git commits with metadata (SHA, date, files, message)
- Filter commits by time range or starting commit
- Extract and filter git trailers (e.g., `Co-authored-by`, `User-Facing`)
- Output in simple text or JSON format
- Pipe output to AI tools (OpenAI, Gemini, Claude) for automated summarization
## Installation
### Using uv (Recommended)
No installation needed! The tool can be run directly:
```bash
uv run git-history-extraction --help
```
### Install as Package
```bash
pip install git-history-extraction
```
## Usage
### Basic Examples
Extract commits from the last 24 hours (default):
```bash
git-history-extraction
```
Extract commits from the last 7 days:
```bash
git-history-extraction --since "7 days ago"
```
Extract commits from a specific repository:
```bash
git-history-extraction --repo /path/to/repo --since "1 week ago"
```
### Output Formats
Simple text format (default):
```bash
git-history-extraction --since "1 day ago"
```
JSON format for piping to other tools:
```bash
git-history-extraction --since "1 day ago" --format json
```
### Commit Range Selection
By time range:
```bash
git-history-extraction --since "2024-01-01"
```
From a specific commit to HEAD:
```bash
git-history-extraction --since-commit abc1234
```
### Git Trailers
Extract specific trailers only (case-insensitive):
```bash
git-history-extraction --since "1 week ago" --trailers "co-authored-by,reviewed-by"
```
## Piping to AI Tools for Summarization
This tool extracts and formats git history, making it easy to pipe to AI tools for summarization. The tool itself **does not perform AI summarization**—it prepares the data so you can use your preferred AI tool.
The tool enables you to extract targeted slices of git history for different audiences. For example, use git trailers like `User-Facing:` to mark end-user changes, then extract and pipe them to AI for changelogs or internal notifications.
### Creating Structured Git Trailers with AI
Combine with [aiautocommit](https://github.com/iloveitaly/aiautocommit) to automatically generate git trailers during commits. This creates a structured history that can be easily filtered and summarized for different audiences.
**Example custom commit prompt for aiautocommit:**
```markdown
# IMPORTANT: Your Instructions
You are an expert software developer. Generate a commit message from the `git diff` output below using these rules:
## 1. Subject Line
- Use a conventional commit prefix:
- `feat`: New features
- `fix`: Bug fixes, including user-visible design or style fixes.
- `docs`: Changes only to internal documentation (e.g., `.md`, `.rst`) or code comments.
- `style`: Formatting, linting, or code style changes in code files.
- `refactor`: Code structure improvements (no behavior changes).
- `build`: Updates to build scripts or configs (e.g., `Makefile`, `Justfile`, `Dockerfile`, `package.json`).
- `deploy`: Deployment script or IAC updates.
- `test`: Changes to tests
- Add optional scope in parentheses when changes affect a specific module (e.g., `feat(auth): add login`)
- Limit to 50 characters after the prefix and scope.
- Use imperative mood (e.g., "improve layout").
- Describe the intent or outcome (e.g., "prevent text overflow" not "add break-all").
- Be specific about the change ("validate email format" not "improve validation").
## 2. Extended Commit Message
- Include only if changes have non-obvious implications, fix complex bugs, or introduce breaking changes.
- Separate from subject with one blank line.
- Use markdown bullets focusing on **why** the change was needed and **what impact** it has.
- Mention side effects, user impact, or important trade-offs.
## 3. User-facing Changes
If the change is something that a end-user (not internal admin!) would see, include a `User-facing:` git trailer with a sentence
or two explaining, to the user, what they would see differently because of this change.
## 4. General Guidelines
- Prioritize the purpose of changes over listing tools or properties used.
- Keep concise; avoid obvious or verbose details.
- Always generate a message based on the diff, even with limited context.
## 5. Scopes
Optional scopes (e.g., `feat(api):`):
- `match`: frontend or backend changes tied
- `site`: content, additional pages, etc for the static site content
- `internal-admin`: internal admin changes (including CMS)
```
With this setup, commits automatically get `User-facing:` trailers. You can then extract and summarize them:
```bash
# Extract only user-facing changes from the last sprint
git-history-extraction --since "last monday" --trailers "User-facing" | \
gemini -i "Create a user-friendly changelog from these changes"
```
### Using with Gemini CLI
Extract user-facing changes and generate a non-technical summary:
```bash
git-history-extraction --repo . --since "last monday" \
--trailers "User-Facing" | \
gemini -i "This is a compressed git history identifying user-facing changes. \
Can you write a 1-2 sentence overview of the changes, with a list of bullets \
identifying changes. This is for a non-technical internal audience, letting \
them know what the development team has done. Separate into 'new' and 'fixed' \
sections. Include a 'Updates Since' with the date of the first commit in the \
history. Remove fluff, keep it concise and information dense."
```
### Using the OpenAI Playground Script (Optional)
An optional playground script is included that demonstrates OpenAI integration:
```bash
# Generate summary with OpenAI
git-history-extraction --since "1 week ago" --format json | \
uv run playground/summarize_commits.py
# Preview the prompt without calling OpenAI
git-history-extraction --since "1 week ago" --format json | \
uv run playground/summarize_commits.py --dump-prompt
```
**Requirements:**
- `OPENAI_API_KEY` environment variable
- The script uses GPT-4o-mini by default
This is just an example—you can pipe to any AI tool you prefer. See [playground/README.md](playground/README.md) for more details.
## Output Format
### Simple Format
Each commit is displayed with:
- **Commit:** SHA hash
- **Date:** ISO 8601 timestamp
- **Files:** Comma-separated list of changed files
- **Message:** Commit body with trailers removed
### JSON Format
Array of commit objects:
```json
[
{
"sha": "abc123...",
"date": "2024-10-31T08:00:00-06:00",
"body": "commit message with trailers",
"files": ["file1.py", "file2.md"]
}
]
```
## Options
| Option | Description | Default |
|--------|-------------|---------|
| `--since TEXT` | ISO date/time or relative time | `"24 hours ago"` |
| `--since-commit TEXT` | Start from specific commit (overrides `--since`) | None |
| `--repo DIRECTORY` | Path to git repository | `.` (current directory) |
| `--trailers TEXT` | Comma-separated trailer keys to extract | None (show all) |
| `--format [simple\|json]` | Output format | `simple` |
## How It Works
- Uses `git log` with custom formatting for efficient single-pass extraction
- Parses commit metadata, body, and file changes in one command
- Intelligently extracts git trailers from commit messages
- No per-commit subprocess calls for optimal performance
## Development
The main logic lives in `git_history_extraction/__init__.py`. The tool is structured as a Python package with:
- **main.py:** Entry point script
- **git_history_extraction/:** Core module with extraction logic
- **playground/:** Optional AI summarization scripts
### Running Tests
```bash
pytest
```
## Limitations
- Large commit ranges may generate significant output; consider narrowing the time range
- This tool extracts and formats data only—AI summarization requires external tools
- Git must be available in PATH
## Requirements
- Python >= 3.9
- git
- [uv](https://docs.astral.sh/uv/) (recommended) or pip
Raw data
{
"_id": null,
"home_page": null,
"name": "git-history-extraction",
"maintainer": null,
"docs_url": null,
"requires_python": ">=3.10",
"maintainer_email": null,
"keywords": "git, changelog, history, commit, trailers, ai, summarization, openai, gemini",
"author": "Michael Bianco",
"author_email": "Michael Bianco <mike@mikebian.co>",
"download_url": "https://files.pythonhosted.org/packages/ec/cd/c1b3e40426b6a61b83327c495d8e6178035a85c26d04cd8d1c30ea9f364e/git_history_extraction-0.2.0.tar.gz",
"platform": null,
"description": "# git-history-extraction\n\nA tool to extract and filter git commit history, making it easy to pipe to AI tools for changelog generation and summaries.\n\n## Features\n\n- Extract git commits with metadata (SHA, date, files, message)\n- Filter commits by time range or starting commit\n- Extract and filter git trailers (e.g., `Co-authored-by`, `User-Facing`)\n- Output in simple text or JSON format\n- Pipe output to AI tools (OpenAI, Gemini, Claude) for automated summarization\n\n## Installation\n\n### Using uv (Recommended)\n\nNo installation needed! The tool can be run directly:\n\n```bash\nuv run git-history-extraction --help\n```\n\n### Install as Package\n\n```bash\npip install git-history-extraction\n```\n\n## Usage\n\n### Basic Examples\n\nExtract commits from the last 24 hours (default):\n```bash\ngit-history-extraction\n```\n\nExtract commits from the last 7 days:\n```bash\ngit-history-extraction --since \"7 days ago\"\n```\n\nExtract commits from a specific repository:\n```bash\ngit-history-extraction --repo /path/to/repo --since \"1 week ago\"\n```\n\n### Output Formats\n\nSimple text format (default):\n```bash\ngit-history-extraction --since \"1 day ago\"\n```\n\nJSON format for piping to other tools:\n```bash\ngit-history-extraction --since \"1 day ago\" --format json\n```\n\n### Commit Range Selection\n\nBy time range:\n```bash\ngit-history-extraction --since \"2024-01-01\"\n```\n\nFrom a specific commit to HEAD:\n```bash\ngit-history-extraction --since-commit abc1234\n```\n\n### Git Trailers\n\nExtract specific trailers only (case-insensitive):\n```bash\ngit-history-extraction --since \"1 week ago\" --trailers \"co-authored-by,reviewed-by\"\n```\n\n## Piping to AI Tools for Summarization\n\nThis tool extracts and formats git history, making it easy to pipe to AI tools for summarization. The tool itself **does not perform AI summarization**\u2014it prepares the data so you can use your preferred AI tool.\n\nThe tool enables you to extract targeted slices of git history for different audiences. For example, use git trailers like `User-Facing:` to mark end-user changes, then extract and pipe them to AI for changelogs or internal notifications.\n\n### Creating Structured Git Trailers with AI\n\nCombine with [aiautocommit](https://github.com/iloveitaly/aiautocommit) to automatically generate git trailers during commits. This creates a structured history that can be easily filtered and summarized for different audiences.\n\n**Example custom commit prompt for aiautocommit:**\n\n```markdown\n# IMPORTANT: Your Instructions\n\nYou are an expert software developer. Generate a commit message from the `git diff` output below using these rules:\n\n## 1. Subject Line\n\n- Use a conventional commit prefix:\n - `feat`: New features\n - `fix`: Bug fixes, including user-visible design or style fixes.\n - `docs`: Changes only to internal documentation (e.g., `.md`, `.rst`) or code comments.\n - `style`: Formatting, linting, or code style changes in code files.\n - `refactor`: Code structure improvements (no behavior changes).\n - `build`: Updates to build scripts or configs (e.g., `Makefile`, `Justfile`, `Dockerfile`, `package.json`).\n - `deploy`: Deployment script or IAC updates.\n - `test`: Changes to tests\n- Add optional scope in parentheses when changes affect a specific module (e.g., `feat(auth): add login`)\n- Limit to 50 characters after the prefix and scope.\n- Use imperative mood (e.g., \"improve layout\").\n- Describe the intent or outcome (e.g., \"prevent text overflow\" not \"add break-all\").\n- Be specific about the change (\"validate email format\" not \"improve validation\").\n\n## 2. Extended Commit Message\n\n- Include only if changes have non-obvious implications, fix complex bugs, or introduce breaking changes.\n- Separate from subject with one blank line.\n- Use markdown bullets focusing on **why** the change was needed and **what impact** it has.\n- Mention side effects, user impact, or important trade-offs.\n\n## 3. User-facing Changes\n\nIf the change is something that a end-user (not internal admin!) would see, include a `User-facing:` git trailer with a sentence\nor two explaining, to the user, what they would see differently because of this change.\n\n## 4. General Guidelines\n\n- Prioritize the purpose of changes over listing tools or properties used.\n- Keep concise; avoid obvious or verbose details.\n- Always generate a message based on the diff, even with limited context.\n\n## 5. Scopes\n\nOptional scopes (e.g., `feat(api):`):\n\n- `match`: frontend or backend changes tied\n- `site`: content, additional pages, etc for the static site content\n- `internal-admin`: internal admin changes (including CMS)\n```\n\nWith this setup, commits automatically get `User-facing:` trailers. You can then extract and summarize them:\n\n```bash\n# Extract only user-facing changes from the last sprint\ngit-history-extraction --since \"last monday\" --trailers \"User-facing\" | \\\n gemini -i \"Create a user-friendly changelog from these changes\"\n```\n\n### Using with Gemini CLI\n\nExtract user-facing changes and generate a non-technical summary:\n```bash\ngit-history-extraction --repo . --since \"last monday\" \\\n --trailers \"User-Facing\" | \\\n gemini -i \"This is a compressed git history identifying user-facing changes. \\\nCan you write a 1-2 sentence overview of the changes, with a list of bullets \\\nidentifying changes. This is for a non-technical internal audience, letting \\\nthem know what the development team has done. Separate into 'new' and 'fixed' \\\nsections. Include a 'Updates Since' with the date of the first commit in the \\\nhistory. Remove fluff, keep it concise and information dense.\"\n```\n\n### Using the OpenAI Playground Script (Optional)\n\nAn optional playground script is included that demonstrates OpenAI integration:\n\n```bash\n# Generate summary with OpenAI\ngit-history-extraction --since \"1 week ago\" --format json | \\\n uv run playground/summarize_commits.py\n\n# Preview the prompt without calling OpenAI\ngit-history-extraction --since \"1 week ago\" --format json | \\\n uv run playground/summarize_commits.py --dump-prompt\n```\n\n**Requirements:**\n- `OPENAI_API_KEY` environment variable\n- The script uses GPT-4o-mini by default\n\nThis is just an example\u2014you can pipe to any AI tool you prefer. See [playground/README.md](playground/README.md) for more details.\n\n## Output Format\n\n### Simple Format\n\nEach commit is displayed with:\n- **Commit:** SHA hash\n- **Date:** ISO 8601 timestamp\n- **Files:** Comma-separated list of changed files\n- **Message:** Commit body with trailers removed\n\n### JSON Format\n\nArray of commit objects:\n```json\n[\n {\n \"sha\": \"abc123...\",\n \"date\": \"2024-10-31T08:00:00-06:00\",\n \"body\": \"commit message with trailers\",\n \"files\": [\"file1.py\", \"file2.md\"]\n }\n]\n```\n\n## Options\n\n| Option | Description | Default |\n|--------|-------------|---------|\n| `--since TEXT` | ISO date/time or relative time | `\"24 hours ago\"` |\n| `--since-commit TEXT` | Start from specific commit (overrides `--since`) | None |\n| `--repo DIRECTORY` | Path to git repository | `.` (current directory) |\n| `--trailers TEXT` | Comma-separated trailer keys to extract | None (show all) |\n| `--format [simple\\|json]` | Output format | `simple` |\n\n## How It Works\n\n- Uses `git log` with custom formatting for efficient single-pass extraction\n- Parses commit metadata, body, and file changes in one command\n- Intelligently extracts git trailers from commit messages\n- No per-commit subprocess calls for optimal performance\n\n## Development\n\nThe main logic lives in `git_history_extraction/__init__.py`. The tool is structured as a Python package with:\n\n- **main.py:** Entry point script\n- **git_history_extraction/:** Core module with extraction logic\n- **playground/:** Optional AI summarization scripts\n\n### Running Tests\n\n```bash\npytest\n```\n\n## Limitations\n\n- Large commit ranges may generate significant output; consider narrowing the time range\n- This tool extracts and formats data only\u2014AI summarization requires external tools\n- Git must be available in PATH\n\n## Requirements\n\n- Python >= 3.9\n- git\n- [uv](https://docs.astral.sh/uv/) (recommended) or pip\n",
"bugtrack_url": null,
"license": null,
"summary": "Extract and analyze git commit history with support for filtering by trailers, date ranges, and AI-powered summarization for changelogs",
"version": "0.2.0",
"project_urls": {
"Repository": "https://github.com/iloveitaly/git-history-extraction"
},
"split_keywords": [
"git",
" changelog",
" history",
" commit",
" trailers",
" ai",
" summarization",
" openai",
" gemini"
],
"urls": [
{
"comment_text": null,
"digests": {
"blake2b_256": "50632f8efd83a41227bec296a71cf7024d6c6330c12c251c1fbb34478f1ca683",
"md5": "21b243487d2ef1bc08b0ad8ca3029a37",
"sha256": "6415f2a76a5f39acecee9d57e54859805fa077a61e2aec3d303d926f2fdc58fa"
},
"downloads": -1,
"filename": "git_history_extraction-0.2.0-py3-none-any.whl",
"has_sig": false,
"md5_digest": "21b243487d2ef1bc08b0ad8ca3029a37",
"packagetype": "bdist_wheel",
"python_version": "py3",
"requires_python": ">=3.10",
"size": 7337,
"upload_time": "2025-11-01T18:54:09",
"upload_time_iso_8601": "2025-11-01T18:54:09.189657Z",
"url": "https://files.pythonhosted.org/packages/50/63/2f8efd83a41227bec296a71cf7024d6c6330c12c251c1fbb34478f1ca683/git_history_extraction-0.2.0-py3-none-any.whl",
"yanked": false,
"yanked_reason": null
},
{
"comment_text": null,
"digests": {
"blake2b_256": "eccdc1b3e40426b6a61b83327c495d8e6178035a85c26d04cd8d1c30ea9f364e",
"md5": "a9ca088bf8f12b34e216ff57fd64fd8a",
"sha256": "29f003d5243946b7e6d5da1c9fdaeca6b3bf340999897d83e7f7ee70e7502142"
},
"downloads": -1,
"filename": "git_history_extraction-0.2.0.tar.gz",
"has_sig": false,
"md5_digest": "a9ca088bf8f12b34e216ff57fd64fd8a",
"packagetype": "sdist",
"python_version": "source",
"requires_python": ">=3.10",
"size": 6376,
"upload_time": "2025-11-01T18:54:10",
"upload_time_iso_8601": "2025-11-01T18:54:10.212751Z",
"url": "https://files.pythonhosted.org/packages/ec/cd/c1b3e40426b6a61b83327c495d8e6178035a85c26d04cd8d1c30ea9f364e/git_history_extraction-0.2.0.tar.gz",
"yanked": false,
"yanked_reason": null
}
],
"upload_time": "2025-11-01 18:54:10",
"github": true,
"gitlab": false,
"bitbucket": false,
"codeberg": false,
"github_user": "iloveitaly",
"github_project": "git-history-extraction",
"travis_ci": false,
"coveralls": false,
"github_actions": true,
"lcname": "git-history-extraction"
}
JSON
