Automatic, per-branch Git commit indexing for EagleKit projects. Adds [index][branch] prefixes, assigns stable UUIDs for cross-branch correlation, and stores rich metadata — enabling safer history management, future synchronization tooling, and enhanced traceability.
If you already have EagleKit installed with pipx, use inject to add the plugin to the same environment:
pipx inject eaglekit eaglekit-plugin-commit-tracker
ek tracker --helpIf you're installing for the first time (without EagleKit yet):
pipx install eaglekit-plugin-commit-tracker
# This will automatically install eaglekit as a dependency
ek tracker --help# If installed with inject
pipx inject eaglekit eaglekit-plugin-commit-tracker --force
# If installed standalone
pipx upgrade eaglekit-plugin-commit-tracker# If installed with inject
pipx runpip eaglekit uninstall eaglekit-plugin-commit-tracker
# If installed standalone
pipx uninstall eaglekit-plugin-commit-trackerFor development or when using a virtual environment:
pip install eaglekit-plugin-commit-trackerFor editable installation (plugin development):
git clone <repo-url>
cd eaglekit-plugin-commit-tracker
pip install -e .- Python >= 3.9
- Git installed on PATH
- EagleKit CLI framework
After installation, the plugin command group becomes available:
ek tracker --helpInitialize tracking in a Git-enabled EagleKit project:
ek tracker initMake commits (prefix added automatically):
git commit -m "Add authentication"
# → [1][main] Add authenticationInspect:
ek tracker status
ek tracker show --limit 5Adjust counter:
ek tracker get-counter
ek tracker set-counter 10Skip one commit:
ek tracker skip
git commit -m "Temp tweak (no prefix)"Uninstall (optionally wiping data):
ek tracker uninstall # Remove hooks only
ek tracker uninstall --clean # Remove all tracking data
ek tracker uninstall --clean-branch feature-x- Automatic
[index][branch]prefix insertion (prepare-commit-msghook) - Per-branch sequential counter management
- UUID (logical commit ID) assignment for cross-branch tracking
- JSON metadata store under
.git/eaglekit_commit_tracker/ - Safe internal operations: list, status, counter management, reindex
- History rewrite support with structured backups (optional, explicit)
- Backward compatibility legacy
.mapfile support - Integration path for mirror / sync plugins (logical IDs preserved)
| Command | Purpose | Modifies Git History? | Shared Branch Safe? |
|---|---|---|---|
ek tracker init |
Install commit tracking hooks | No | Yes |
ek tracker status |
Show installation & current branch state | No | Yes |
ek tracker show [-b BRANCH] [--limit N] |
List tracked commits | No | Yes |
ek tracker skip |
Skip next commit indexing | No | Yes |
ek tracker get-counter [-b BRANCH] |
Show counter & next index | No | Yes |
ek tracker set-counter VALUE [-b BRANCH] |
Set counter manually | No | Yes |
ek tracker reindex [-b BRANCH] |
Recompute internal indices only | No | Yes |
ek tracker add-index COMMIT INDEX [-b BRANCH] |
Assign index to existing commit (metadata only) | No | Yes |
ek tracker rename-branch NEW_NAME |
Rename tracked branch data | No | Yes |
ek tracker rewrite [--dry-run] [--force] |
Rewrite commit messages with prefixes | YES | No |
| `ek tracker uninstall [--clean | --clean-branch B]` | Remove hooks / data | No |
Legend: Safe = does not change existing commit objects. Rewrite = requires force push.
prepare-commit-msghook assigns next index + UUID and injects[index][branch]if absent.post-commithook records metadata (hash, UUID, author, date, index) into JSON + legacy map.- Repository layer (
BranchRepository) persists branch states and rewrite backups. - CLI (Typer) exposes ergonomic commands; destructive actions require explicit confirmation (
--dry-run/--force). - Rewrites snapshot mappings for future tooling (e.g., potential revert/export operations).
Storage layout:
.git/
eaglekit_commit_tracker/
branches/<branch>.json
rewrites/<rewrite_id>.json
ai_prefix_counters/<branch>.map # Legacy compatibility
- Default workflow is non-destructive. Use
reindexfor logical continuity without altering Git history. rewritechanges commit hashes. Always review with--dry-runfirst, then apply with--forceand push viagit push --force-with-lease.- Skipping: use
ek tracker skipor environment variableSKIP_EAGLEKIT_HOOK=1. - Branch rename flow:
git branch -m old newthenek tracker rename-branch new. - Backups: every rewrite stores a JSON snapshot of mappings.
Editable installation:
git clone <repo-url>
cd eaglekit-plugin-commit-tracker
python -m venv .venv
source .venv/bin/activate
pip install -e .Code structure:
src/eaglekit_plugin_commit_tracker/
__init__.py # register(app)
_impl.py # CLI + hooks + command implementations
entities.py # Domain models (CommitEntry, BranchState, etc.)
repository.py # Persistence abstraction
Contribution guidelines:
- Keep commands idempotent where possible.
- Mark dangerous operations clearly in help text.
- Preserve JSON schema compatibility (additive changes preferred).
ek tracker rewrite --dry-run
ek tracker rewrite --force
git push --force-with-lease origin main
ek tracker reindexUse only when commit messages must visibly reflect corrected numbering. Prefer reindex otherwise.
MIT — see LICENSE.
This plugin is part of the EagleKit ecosystem and demonstrates clean layering, safety-first history operations, and integration-ready commit metadata.
-
Sequential Indexing: Automatically adds
[num][branch]prefix to commits -
UUID Tracking: Each commit gets a unique logical ID for cross-branch tracking
-
Branch-specific Metadata: Stores complete commit history per branch in JSON## What it does## What it does
-
Mirror Integration: Designed to work seamlessly with
eaglekit-plugin-mirror -
History Rewrite with Backup: Safely rewrite Git history with automatic backup for revert
📦 InstallationAutomatically prepends [num][branch] to commit messages using a prepare-commit-msg hook.Installs a prepare-commit-msg hook that automatically prepends [num][branch] to each commit message:
pip install -e .
```## Installation```
Once installed, the `ek tracker` command group becomes available.[1][feature-x] Initial commit
## 🚀 Quick Start```bash[2][feature-x] Add authentication
```bashpip install eaglekit-plugin-commit-tracker[3][feature-x] Fix bug in login
# Initialize tracking
ek tracker init``````
# Make commits normally - they'll be auto-prefixed
git commit -m "Add feature"
# Result: [1][main] Add featureOnce installed, the `ek tracker` command group becomes available.## Installation
# View tracked commits
ek tracker show
## Features```bash
# Check status
ek tracker statuspip install eaglekit-plugin-commit-tracker
- Automatic commit message prefixing with sequential numbers```
- Per-branch counter tracking
| Command | Description | Modifies Git? |
|---------|-------------|---------------|- Git hooks integrationOnce installed, the ek tracker command group becomes available.
| init | Install tracking hooks | No |
| uninstall | Remove hooks (+ optional data cleanup) | No |
| status | Show tracking system status | No |
| show | List tracked commits | No |## Development## Commands
| skip | Skip next commit | No |
| get-counter | View current counter | No |
| set-counter | Set counter value | No |
| reindex | Fix internal indices | No |This is a plugin for Eagle Kit that extends its functionality with Git hooks support.### Basic Commands
| add-index | Assign index to commit | No |
| rename-branch | Rename branch in tracking | No |
| rewrite | Add prefixes to Git history | YES ek tracker install [project]
Install the commit message hook in a project.
### `ek tracker init`ek tracker install my-project
Initialize commit tracking by installing Git hooks.ek tracker install # Use current directory
ek tracker init # Current directory#### `ek tracker uninstall [project] [--clean] [--clean-branch]`
ek tracker init my-project # Named projectRemove the hook from a project.
### `ek tracker status`# Remove only the hooks (keeps counter data)
Show tracking system status.ek tracker uninstall my-project
```bash# Remove hooks AND all counter/mapping data
ek tracker statusek tracker uninstall my-project --clean
List tracked commits with details.```
ek tracker show # Current branch- `--clean`: Remove all `.git/ai_prefix_counters/` data (all branches)
ek tracker show --branch main # Specific branch- `--clean-branch <name>`: Remove data only for the specified branch
ek tracker show --limit 10 # Limit results
```**What gets removed:**
- Always: `prepare-commit-msg` and `post-commit` hooks
### `ek tracker uninstall`- With `--clean`: All counter files and mapping data
Remove hooks and optionally clean tracking data.- With `--clean-branch`: Counter and mapping for one branch only
```bash#### `ek tracker status [project]`
ek tracker uninstall # Remove hooks onlyCheck if the hook is installed and where.
ek tracker uninstall --clean # Remove hooks + all data
ek tracker uninstall --clean-branch feature-x # Specific branch```bash
```ek tracker status my-project
Skip automatic indexing for the next commit.#### ek tracker reset [project] [--branch]
Reset the commit counter to 0.
ek tracker skip```bash
git commit -m "Temporary fix"ek tracker reset my-project # Reset current branch
```ek tracker reset my-project --branch main # Reset specific branch
Display current counter value.### Advanced Commands
```bash#### ek tracker skip <message> [options]
ek tracker get-counterMake a commit without the hook prefix.
ek tracker get-counter --branch main
ek tracker skip "Quick fix" --project my-project
### `ek tracker set-counter <value>`ek tracker skip "Update docs" -a # Add all changes first
Set counter to specific value.```
```bashOptions:
ek tracker set-counter 100- `-a, --all`: Add all changes before committing
```- `--project`: Specify project name
- `--ws`: Specify workspace path
### `ek tracker reindex`
Reassign internal indices sequentially (doesn't modify Git).#### `ek tracker reindex [project] [--branch]`
Analyze all commits in the branch and reindex them sequentially, fixing any skipped numbers.
```bash
ek tracker reindex```bash
ek tracker reindex --branch mainek tracker reindex my-project
```ek tracker reindex my-project --branch feature-x
```
### `ek tracker add-index <commit> <index>`
Manually assign index to a specific commit.**Note:** This updates the internal index mapping but doesn't modify Git history. The original commit messages remain unchanged.
```bash#### `ek tracker add-index <commit-id> <index> [options]`
ek tracker add-index abc1234 5Manually assign an index to a specific commit.
ek tracker add-index HEAD 10
``````bash
# Only update internal mapping (safe, default)
### `ek tracker rename-branch <new-name>`ek tracker add-index abc1234 5 --project my-project
Rename current branch in tracking (auto-detects old name).ek tracker add-index HEAD 10 # Use current commit
```bash# Rewrite the commit message in Git history
git branch -m old-name new-nameek tracker add-index abc1234 5 --rewrite
ek tracker rename-branch new-name
```# Add index without updating the counter
ek tracker add-index abc1234 3 --no-update-counter
### `ek tracker rewrite` ⚠️```
Rewrite Git history to add prefixes (dangerous).
Options:
```bash- `--rewrite`: Actually modify the commit message in Git history (⚠️ rewrites history)
# Preview changes- `--update-counter/--no-update-counter`: Update the branch counter to this index (default: yes)
ek tracker rewrite --dry-run- `--branch`: Specify branch (defaults to current)
- `--project`: Project name
# Apply rewrite- `--ws`: Workspace path
ek tracker rewrite --force
**How it works:**
# Rewrite specific range- **Without `--rewrite`** (default): Only updates the internal `.map` file, Git history unchanged
ek tracker rewrite --from abc123 --to HEAD --force- **With `--rewrite`**: Modifies the actual commit message in Git, adding or updating the `[index][branch]` prefix
- **Counter update**: If the new index is higher than the current counter, it updates the counter so the next commit continues from there
# Custom starting index
ek tracker rewrite --start-index 100 --force#### `ek tracker get-counter [project] [--branch]`
```Get the current counter value for a branch.
**⚠️ WARNING:** Rewrites Git history! Automatic backup saved for revert.```bash
ek tracker get-counter my-project
## 🏗️ Architectureek tracker get-counter --branch feature-x
```
### Data Storage
Output example:
.git/Current counter for branch 'main': 5
├── hooks/Next commit will be: [6][main]
│ ├── prepare-commit-msg # Adds [num][branch] prefix```
│ └── post-commit # Records commit metadata
└── eaglekit_commit_tracker/#### ek tracker set-counter <value> [options]
├── branches/Set the counter value for a branch.
│ ├── main.json # Branch-specific tracking
│ └── develop.json```bash
└── rewrites/ek tracker set-counter 10 --project my-project
└── <uuid>.json # History rewrite backupsek tracker set-counter 0 --branch main # Reset to 0
### Commit FlowThis is useful when you want to control what number the next commit will use.
1. **You commit:** `git commit -m "Add feature"`Example:
2. **prepare-commit-msg:** Adds `[1][main]` prefix + generates UUID```bash
3. **Git creates commit:** Hash `abc123...` with prefixed message# Set counter to 5
4. **post-commit:** Saves metadata (hash, UUID, author, date) to JSONek tracker set-counter 5
### UUID Tracking for Mirror# Next commit will be [6][main]
git commit -m "New feature" # → [6][main] New feature
```bash```
# Main branch
git commit -m "Fix bug"#### `ek tracker list [project] [--branch] [--limit] [--all]`
# → [5][main] Fix bug (UUID: 550e8400-...)List commits tracked by the hook with their index, prefix, message, and commit ID.
# Cherry-pick to develop```bash
git cherry-pick abc123# Show only tracked commits (default)
# → [3][develop] Fix bug (UUID: 550e8400-...)ek tracker list my-project
# Same UUID, different hash!
```# Show all commits on the branch
ek tracker list my-project --all
## 🔧 Integration with Mirror Plugin
# Limit number of commits shown
- **UUID Preservation**: Maintains logical commit IDs across branchesek tracker list my-project --limit 10
- **Cross-repo Tracking**: Track same commit in different repositories
- **Metadata Storage**: Mirror plugin can read/write tracking data# Show tracked commits on specific branch
ek tracker list --branch main
## 🎬 Common Workflows```
### Add Tracking to Existing RepoOutput example (default - only tracked):
```
```bashTracked commits on branch 'feature-x':
ek tracker init
ek tracker rewrite --dry-run # Preview [3][feature-x] Add authentication
ek tracker rewrite --force # Apply └─ def5678
git push --force-with-lease origin main
``` [2][feature-x] Fix bug
└─ abc1234
### Rename Branch
[1][feature-x] Initial commit
```bash └─ xyz9012
git branch -m old new
ek tracker rename-branch newTotal tracked: 3 commits
```Use --all to see all commits on this branch
```
### Fix Counter
Output example (with --all):
```bash```
ek tracker get-counterAll commits on branch 'feature-x':
ek tracker set-counter 100
# Or: ek tracker reindex [3][feature-x] Add authentication
``` └─ def5678
## 🛡️ Safety Features [ ] Quick fix without prefix
└─ ghi9012
- **Dry Run**: Preview before applying
- **Automatic Backups**: Rewrite operations save complete mapping [2][feature-x] Fix bug
- **Force Confirmation**: Dangerous operations require `--force` └─ abc1234
- **Non-Destructive**: Most commands don't modify Git
[1][feature-x] Initial commit
## 📝 License └─ xyz9012
```
MIT
Options:
- `--branch`: Specify branch (defaults to current)
- `-n, --limit`: Max number of commits to show (default: all tracked)
- `--all`: Show all commits from Git history, not just tracked ones
**How it works:**
- **Default behavior**: Shows only commits that are in the internal `.map` file (commits tracked by the hook)
- **With `--all`**: Shows all commits from Git history, including those without prefixes
#### `ek tracker rename-branch <old-name> <new-name> [options]`
Rename the branch name in all commit prefixes, maintaining the indices.
```bash
ek tracker rename-branch feature-x feature-auth --project my-project
```
**⚠️ WARNING:** This rewrites Git history! Use with caution, especially on shared branches.
Before:
```
[1][feature-x] Initial commit
[2][feature-x] Add login
```
After:
```
[1][feature-auth] Initial commit
[2][feature-auth] Add login
```
#### `ek tracker rewrite [project] [--branch] [--force]`
Rewrite Git history to fix all index numbers sequentially. Unlike `reindex`, this actually modifies the commit messages in Git.
```bash
ek tracker rewrite my-project
ek tracker rewrite my-project --branch main
ek tracker rewrite my-project --force # Skip confirmation
```
**⚠️ WARNING:** This rewrites Git history! Use with caution, especially on shared branches.
Before:
```
[1][main] First commit
[5][main] Skipped some numbers
[6][main] Another commit
```
After (commit messages are actually changed in Git):
```
[1][main] First commit
[2][main] Skipped some numbers
[3][main] Another commit
```
**Difference from `reindex`:**
- `reindex`: Only updates internal mapping, Git history unchanged (safe)
- `rewrite`: Actually modifies commit messages in Git history (requires force push)
Options:
- `--branch`: Specify branch (defaults to current)
- `--force`: Skip confirmation prompt
## How it works
### Automatic Indexing
- Each branch maintains its own counter in `.git/ai_prefix_counters/<branch>`
- The counter increments with each commit
- Commit ID mapping is stored in `.git/ai_prefix_counters/<branch>.map`
### What Gets Skipped
The hook automatically skips:
- Merge commits (`--merge`)
- Squash merges (`--squash`)
- Cherry-picks (`--cherry-pick`)
- Amended commits (`--amend`)
- Commits when `SKIP_EAGLEKIT_HOOK=1` environment variable is set
### Manual Skip
You can skip the hook for individual commits:
```bash
# Using the skip command (recommended)
ek tracker skip "Quick fix"
# Using environment variable
SKIP_EAGLEKIT_HOOK=1 git commit -m "Quick fix"
```
### Data Storage
```
.git/
└── ai_prefix_counters/
├── main # Counter for 'main' branch
├── main.map # Index→CommitID mapping for 'main'
├── feature-x # Counter for 'feature-x' branch
└── feature-x.map # Index→CommitID mapping for 'feature-x'
```
## Use Cases
### Fixing Skipped Numbers (Safe Way - No Git History Change)
If some commits were made without the hook or with `skip`, use `reindex` to update internal tracking:
```bash
# Before (Git history)
[1][main] First commit
[5][main] Skipped some numbers
[6][main] Another commit
# After reindex (Git messages stay the same, but plugin tracks them as 1,2,3)
ek tracker reindex
# Git still shows [1], [5], [6] but plugin treats them as sequential
```
### Fixing Skipped Numbers (Rewrite Git History)
If you want to actually change the commit messages in Git:
```bash
# Before (Git history)
[1][main] First commit
[5][main] Skipped some numbers
[6][main] Another commit
# After rewrite
ek tracker rewrite
# Git now shows:
[1][main] First commit
[2][main] Skipped some numbers ← Changed in Git!
[3][main] Another commit ← Changed in Git!
# Don't forget to force push if this is a shared branch
git push --force-with-lease
```
### Renaming a Branch
If you rename a Git branch, update the prefixes:
```bash
git branch -m old-feature new-feature
ek tracker rename-branch old-feature new-feature
```
### Renaming AND Reindexing
Combine both operations:
```bash
# 1. Rename the Git branch
git branch -m feature-x feature-auth
# 2. Update prefixes in commits
ek tracker rename-branch feature-x feature-auth
# 3. Fix any index gaps
ek tracker rewrite --branch feature-auth
# Result: [1][feature-auth], [2][feature-auth], [3][feature-auth]...
```
### Adding Index to Old Commits
If you have old commits without indices, add them manually:
```bash
# Only track internally (safe)
ek tracker add-index abc1234 1
ek tracker add-index def5678 2
# Actually modify Git history
ek tracker add-index abc1234 1 --rewrite
```
### Managing the Counter
```bash
# Check current counter
ek tracker get-counter
# Output: Current counter for branch 'main': 5
# Next commit will be: [6][main]
# Set counter to a specific value
ek tracker set-counter 10
# Next commit will be [11][main]
# Add index and update counter
ek tracker add-index HEAD 15 --rewrite
# Counter is now 15, next commit will be [16][main]
```
### Workflow Example: Adding Prefix to Old Commit
```bash
# You have an old commit without prefix
git log --oneline
# abc1234 Fixed critical bug
# Option 1: Track it internally (safe)
ek tracker add-index abc1234 5
# Git still shows: "Fixed critical bug"
# But plugin knows it as index 5
# Option 2: Actually add prefix to Git (rewrites history)
ek tracker add-index abc1234 5 --rewrite
# Git now shows: "[5][main] Fixed critical bug"
# Counter updated to 5, next commit will be [6][main]
# Make next commit
git commit -m "New feature"
# → [6][main] New feature
```
## Configuration
The hook honors Git's `core.hooksPath` configuration if set.
## Command Comparison
| Command | Modifies Git History? | Changes Commit Messages? | Fixes Index Gaps? | Safe for Shared Branches? | Use Case |
|---------|----------------------|--------------------------|-------------------|---------------------------|----------|
| `install` | ❌ No | ❌ No | N/A | ✅ Yes | Enable the hook |
| `skip` | ❌ No | ❌ No | N/A | ✅ Yes | Make one commit without prefix |
| `reset` | ❌ No | ❌ No | ❌ No | ✅ Yes | Start counter from 0 |
| `reindex` | ❌ No | ❌ No | ✅ Yes (internally) | ✅ Yes | Track commits sequentially without changing Git |
| `rewrite` | ⚠️ **YES** | ⚠️ **YES** | ✅ Yes (in Git) | ❌ **NO** | Actually fix index numbers in commit messages |
| `rename-branch` | ⚠️ **YES** | ⚠️ **YES** | ❌ No | ❌ **NO** | Change branch name in prefixes |
| `add-index` | ❌ No (default) | ❌ No (default) | N/A | ✅ Yes (default) | Manually assign index to a commit |
| `add-index --rewrite` | ⚠️ **YES** | ⚠️ **YES** | N/A | ❌ **NO** | Assign index AND modify commit message |
| `get-counter` | ❌ No | ❌ No | N/A | ✅ Yes | View current counter value |
| `set-counter` | ❌ No | ❌ No | N/A | ✅ Yes | Set counter for next commit |
| `list` | ❌ No | ❌ No | N/A | ✅ Yes | View commits with their indices |
**Key:**
- ✅ Safe operation
- ⚠️ **Requires `git push --force-with-lease`**
- ❌ Not applicable or doesn't do this