Skip to content

About

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.

Resources

Stars

0 stars

Watchers

0 watching

Forks

Repository files navigation

EagleKit Commit Tracker Plugin

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.


📦 Installation

Recommended: pipx (Isolated Environment)

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 --help

If 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

Upgrade

# If installed with inject
pipx inject eaglekit eaglekit-plugin-commit-tracker --force

# If installed standalone
pipx upgrade eaglekit-plugin-commit-tracker

Uninstall

# If installed with inject
pipx runpip eaglekit uninstall eaglekit-plugin-commit-tracker

# If installed standalone
pipx uninstall eaglekit-plugin-commit-tracker

Alternative: pip (Development/Virtual Environment)

For development or when using a virtual environment:

pip install eaglekit-plugin-commit-tracker

For editable installation (plugin development):

git clone <repo-url>
cd eaglekit-plugin-commit-tracker
pip install -e .

Prerequisites

  • Python >= 3.9
  • Git installed on PATH
  • EagleKit CLI framework

Verify Installation

After installation, the plugin command group becomes available:

ek tracker --help

🚀 Quick Start

Initialize tracking in a Git-enabled EagleKit project:

ek tracker init

Make commits (prefix added automatically):

git commit -m "Add authentication"
# → [1][main] Add authentication

Inspect:

ek tracker status
ek tracker show --limit 5

Adjust counter:

ek tracker get-counter
ek tracker set-counter 10

Skip 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

🎯 Features

  • Automatic [index][branch] prefix insertion (prepare-commit-msg hook)
  • 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 .map file support
  • Integration path for mirror / sync plugins (logical IDs preserved)

🧭 Command Reference

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.

🏗️ Architecture (Summary)

  1. prepare-commit-msg hook assigns next index + UUID and injects [index][branch] if absent.
  2. post-commit hook records metadata (hash, UUID, author, date, index) into JSON + legacy map.
  3. Repository layer (BranchRepository) persists branch states and rewrite backups.
  4. CLI (Typer) exposes ergonomic commands; destructive actions require explicit confirmation (--dry-run / --force).
  5. 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

🛡️ Safety Notes

  • Default workflow is non-destructive. Use reindex for logical continuity without altering Git history.
  • rewrite changes commit hashes. Always review with --dry-run first, then apply with --force and push via git push --force-with-lease.
  • Skipping: use ek tracker skip or environment variable SKIP_EAGLEKIT_HOOK=1.
  • Branch rename flow: git branch -m old new then ek tracker rename-branch new.
  • Backups: every rewrite stores a JSON snapshot of mappings.

🧰 Development

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).

🛡️ History Rewrite Workflow

ek tracker rewrite --dry-run
ek tracker rewrite --force
git push --force-with-lease origin main
ek tracker reindex

Use only when commit messages must visibly reflect corrected numbering. Prefer reindex otherwise.

📝 License

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

📋 Commands Reference

  • 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.

📖 Detailed Command Guide

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

Remove hooks and data for specific branch only

ek tracker showek tracker uninstall my-project --clean-branch feature-x

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

ek tracker skip

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

ek tracker get-counter

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

About

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.

Resources

Stars

0 stars

Watchers

0 watching

Forks

Releases

Packages

Contributors

Languages