Skip to main content

Documentation Index

Fetch the complete documentation index at: https://repr.dev/docs/llms.txt

Use this file to discover all available pages before exploring further.

Repr uses git post-commit hooks to automatically queue commits for story generation. Hooks run silently after each commit—no interruptions, no network calls, just quiet tracking.

​
How It Works

When you install a hook:
  1. Hook installed - repr creates .git/hooks/post-commit in your repo
  2. You commit - Git triggers the hook after each commit
  3. Commit queued - Hook adds commit SHA to ~/.repr/queue
  4. You generate - Run repr generate to turn queued commits into stories
Privacy guarantee: Hooks never make network calls. They just write commit SHAs to a local file.

​
Usage

repr hooks [ACTION] [OPTIONS]

​
Actions

​
install - Set up automatic tracking

Install the hook script in .git/hooks/post-commit. Options:
  • --all - Install in all tracked repositories
  • --repo <path> - Install in a specific repository
Examples: 
# Install in all tracked repos (recommended)
repr hooks install --all

# Install in specific repo
repr hooks install --repo ~/code/myproject
Output: 
Installing hooks in 3 repositories...

  ✓ myproject: hook installed
  ✓ frontend-app: hook installed
  ○ old-project: already installed

Hooks installed: 2, Already installed: 1

​
remove - Uninstall hooks

Remove the hook script from repositories. Options:
  • --all - Remove from all tracked repositories
  • --repo <path> - Remove from a specific repository
Examples: 
# Remove from all repos
repr hooks remove --all

# Remove from specific repo
repr hooks remove --repo ~/code/myproject
Output: 
  ✓ myproject: hook removed
  ✓ frontend-app: hook removed

Hooks removed: 2

​
status - Check hook health

Check which repositories have hooks installed and view queue statistics. Options:
  • --json - Output as JSON for scripting
Examples: 
# Human-readable output
repr hooks status

# JSON output
repr hooks status --json
Output: 
Hook Status

✓ myproject
  Hook installed and active
  Queue: 12 commits

✓ frontend-app
  Hook installed and active
  Queue: 5 commits

○ old-project
  No hook installed
JSON output: 
[
  {
    "name": "myproject",
    "path": "/Users/me/code/myproject",
    "installed": true,
    "executable": true,
    "queue_count": 12
  }
]

​
queue - Internal command

Queue a specific commit (called by the git hook automatically). Usage: 
repr hooks queue <commit_sha> --repo <path>
This is an internal command used by the git post-commit hook. You shouldn’t need to call it manually.

​
What Gets Queued?

The hook captures:
  • Commit SHA (full 40-character hash)
  • Repository path
  • Timestamp
Not captured:
  • Commit diffs
  • File contents
  • Commit messages
Diffs are only read when you run repr generate, not during hook execution.

​
Hook Script

The installed hook is a simple bash script: 
#!/bin/bash
# repr post-commit hook
repr hooks queue $(git rev-parse HEAD) --repo $(git rev-parse --show-toplevel) 2>/dev/null &
exit 0
Key features:
  • Runs in background (&) - doesn’t slow down commits
  • Silent (2>/dev/null) - never interrupts your workflow
  • Always exits 0 - never blocks commits even if repr fails
  • No network calls - purely local file write

​
Workflow Examples

​
Daily Developer Flow

# One-time setup
repr hooks install --all

# Then just work normally
git commit -m "Add user authentication"
git commit -m "Fix session timeout"
git commit -m "Add rate limiting"

# At end of day/week
repr generate --local

# Output:
# Processing 15 queued commits...
# Generated 3 stories

​
Selective Hook Usage

Maybe you want hooks on work projects but not personal ones: 
# Install only on work repos
repr hooks install --repo ~/code/work-project-1
repr hooks install --repo ~/code/work-project-2

# Personal projects: manual generation only
repr repos add ~/code/personal-project
# (no hook installed)

​
Pausing Auto-Tracking

If you want to pause hook-based tracking without removing hooks: 
repr repos pause ~/code/myproject

# The hook stays installed but won't queue commits
# Resume later:
repr repos resume ~/code/myproject

​
Troubleshooting

​
Hook not running after commits

Check if it’s installed: 
repr hooks status
If not installed: 
repr hooks install --repo ~/code/myproject

​
Hook conflicts with existing post-commit

If you already have a post-commit hook, repr’s installer will warn you. You can: Option 1: Merge manually 
# Edit your existing hook
vim ~/code/myproject/.git/hooks/post-commit

# Add this line:
repr hooks queue $(git rev-parse HEAD) --repo $(git rev-parse --show-toplevel) 2>/dev/null &
Option 2: Use hook managers like Husky or Lefthook

​
Queue not clearing after generate

The queue should auto-clear. If it doesn’t: 
# Check queue status
repr hooks status

# Manual workaround: generate again
repr generate --local
If problems persist, run repr doctor for diagnostics.

​
Hook making commits slow

Hooks run in the background and shouldn’t add noticeable latency. If commits feel slow:
  1. Check disk I/O - the hook writes a small file
  2. Check if ~/.repr/queue is huge (>10k entries) - this shouldn’t happen
  3. Run repr doctor to check for issues

​
Security & Privacy

What hooks can’t do:
  • ✗ Make network requests
  • ✗ Read file contents
  • ✗ Access environment variables
  • ✗ Modify your repository
  • ✗ Send data anywhere
What hooks do:
  • ✓ Read commit SHA from git
  • ✓ Write SHA to ~/.repr/queue (local file)
  • ✓ Exit immediately
You can inspect the hook script anytime: 
cat ~/code/myproject/.git/hooks/post-commit
  • repr generate - Process queued commits into stories
  • repr repos pause/resume - Control auto-tracking per repo
  • repr doctor - Diagnose hook issues