git-changelog

A CLI tool that generates changelogs and documents file revisions from git history.

Installation

npm install -g git-changelog

Or install with pnpm:

pnpm install -g git-changelog

Or install with yarn:

yarn global add git-changelog

Or use directly with npx:

npx git-changelog

Usage

git-changelog

Generate changelogs and document file revisions from git history:

Document revisions for a specific file:

git-changelog src/file.ts

Document revisions for a file and follow history across renames:

git-changelog --follow src/file.ts

Generate changelog based on tags:

git-changelog --tags

Generate changelog to a specific file:

git-changelog --tags --output changelog.md

Sample Output

Documenting file revisions:

$ git-changelog src/index.ts
Documenting revisions for file: src/index.ts...
Found 5 commits for this file.

🔸 Commit: a1b2c3d4
diff --git a/src/index.ts b/src/index.ts
index 1234567..89abcdef 100644
--- a/src/index.ts
+++ b/src/index.ts
@@ -1,5 +1,7 @@
 import { Component } from './component';
 
+// New feature: Add user authentication
+import { Auth } from './auth';
+
 export class App {
   constructor() {
     this.component = new Component();

Generating documentation with AI...
Generated documentation:
// Added user authentication module
// - Imported Auth module
// - Integrated authentication into App class

File revision documentation completed.

Generating tag-based changelog:

$ git-changelog --tags
Generating changelog at: CHANGELOG.md...
Found 3 tags.

Processing changes between v1.0.0 and v1.1.0...
### v1.1.0:

### Summary
- 12 files changed
- 8 files added
- 3 files modified
- 1 files deleted

### 🚀 Features
- Add new authentication module
- Implement user profile functionality
- Modified 5 .ts files
- Modified 2 .json files

### 🐛 Bug Fixes
- Fix login validation issue
- Resolve data synchronization problem
- Modified 3 .ts files

### 📚 Documentation
- Update API documentation
- Updated 2 documentation files

### 🧱 Build/CI
- Update dependencies
- Updated 2 build configuration files

### 📁 File Details

**.ts files (6 total):**
- src/new-feature.ts
- src/utils/helper.ts
- src/bug-fix.ts
- ...and 3 more

**.md files (3 total):**
- README.md
- docs/api.md
- CHANGELOG.md

**.yml files (1 total):**
- .github/workflows/ci.yml

### 📊 Statistics
- +245 lines added
- -89 lines deleted
- Net change: +156 lines

Changelog generation completed.

Options

Usage: git-changelog [options] [file]

CLI tool that generates changelogs and documents file revisions from git history

Arguments:
  file                          file to document revisions for

Options:
  -o, --output <file>           output changelog file (default: CHANGELOG.md)
  -t, --tags                    generate changelog based on tags
  -f, --follow                  follow file history across renames
  -p, --prompt-arg <arg>        specify the prompt argument to pass to the AI tool (default: "-p")
  --provider <provider>         specify the AI provider to use (gemini, qwen, claude, codex, continue, or any string) (default: "gemini")
  -h, --help                    display help for command

Examples

# Document revisions for a specific file
git-changelog src/index.ts

# Document revisions and follow file history across renames
git-changelog --follow src/methods/custom_element.ts

# Generate changelog based on tags
git-changelog --tags

# Generate changelog to a specific file
git-changelog --tags --output my-changelog.md

# Use a specific AI provider
git-changelog --provider qwen src/index.ts

# Use custom prompt argument
git-changelog --prompt-arg "--prompt" src/index.ts

# Combine with other options
git-changelog --follow --provider gemini --tags --output docs/changelog.md

Enhanced Changelog Features

The git-changelog tool now provides more detailed information when generating changelogs:

Summarized Content Changes

• Features Summary: Groups similar features and summarizes them instead of listing individual commits
• Bug Fixes Summary: Consolidates bug fixes into meaningful categories
• Performance Improvements: Highlights performance-related changes
• Refactoring Summary: Groups refactoring efforts for better understanding

Detailed File Change Information

• Files Added: Clearly identifies new files added in each release
• Files Modified: Shows which existing files were changed
• Files Deleted: Highlights any files that were removed
• File Grouping: Organizes files by extension type for better readability

Enhanced Change Categorization

• Features: Automatically detects feature additions based on keywords in commit messages and code
• Bug Fixes: Identifies bug fixes by looking for fix-related keywords
• Performance Improvements: Detects performance-related changes
• Refactoring: Identifies code refactoring efforts
• Documentation: Recognizes documentation updates
• Build/CI: Detects changes to build configurations and CI workflows
• Breaking Changes: Highlights breaking changes that may affect users

AI-Powered Documentation Generation

• LLM Integration: Uses AI tools like Gemini, Qwen, Claude, etc. to generate meaningful documentation
• Custom Prompts: Supports custom prompt arguments for AI tools
• Fallback Analysis: Provides simple analysis when AI tools are not available

File History Tracking

• Follow Renames: Uses git log --follow to track file history across renames
• Commit-by-Commit Analysis: Shows changes for each commit in the file's history
• Diff Display: Displays the actual diff for each commit

Improved Statistics

• Line Changes: Shows exact number of lines added and deleted
• Net Change: Calculates the overall change in lines of code
• Commit Count: Displays the number of commits in each release
• Colored Output: Uses colored text for better visual distinction of numbers

Commit History

• Shows the most recent commits in each release
• Helps understand the development activity between releases

File Status Indicators

• 🆕 New files
• 📝 Modified files
• 🗑️ Deleted files

Exclusion of Unwanted Files

• Automatically excludes node_modules directory
• Filters out lock files (package-lock.json, pnpm-lock.yaml, etc.)
• Ignores log files for cleaner output

How it works

For file revision documentation:

1. Gets all commit hashes for the specified file in reverse chronological order
2. Optionally follows file history across renames using git log --follow
3. For each commit, shows the diff and analyzes what changed
4. Uses AI tools to generate meaningful documentation comments
5. Falls back to simple analysis if AI tools are not available
6. Outputs the documentation to the console

For tag-based changelog generation:

1. Gets all git tags sorted in descending order (newest first)
2. For each adjacent pair of tags, gets the diff between them
3. Analyzes the diff to categorize changes (features, bug fixes, etc.)
4. Summarizes content changes instead of listing individual files
5. Generates a formatted changelog entry for each tag
6. Writes the changelog to the specified output file

Requirements

• Node.js >= 12
• Git
• Optional: AI tools (Gemini, Qwen, Claude, etc.) for documentation generation

Development

This project is written in TypeScript with a modular structure:

• bin/changelog.ts - Main CLI implementation
• index.ts - Programmatic API entry point

To build:

npm run build

License

MIT