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

> Manage git hooks for automatic tracking

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

```bash theme={null}
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:**

```bash theme={null}
# Install in all tracked repos (recommended)
repr hooks install --all

# Install in specific repo
repr hooks install --repo ~/code/myproject
```

**Output:**

```text theme={null}
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:**

```bash theme={null}
# Remove from all repos
repr hooks remove --all

# Remove from specific repo
repr hooks remove --repo ~/code/myproject
```

**Output:**

```text theme={null}
  ✓ 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:**

```bash theme={null}
# Human-readable output
repr hooks status

# JSON output
repr hooks status --json
```

**Output:**

```text theme={null}
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:**

```json theme={null}
[
  {
    "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:**

```bash theme={null}
repr hooks queue <commit_sha> --repo <path>
```

<Warning>
  This is an internal command used by the git post-commit hook. You shouldn't need to call it manually.
</Warning>

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

```bash theme={null}
#!/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

```bash theme={null}
# 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:

```bash theme={null}
# 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:

```bash theme={null}
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:

```bash theme={null}
repr hooks status
```

If not installed:

```bash theme={null}
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

```bash theme={null}
# 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](https://typicode.github.io/husky/) or [Lefthook](https://github.com/evilmartians/lefthook)

### Queue not clearing after generate

The queue should auto-clear. If it doesn't:

```bash theme={null}
# 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:

```bash theme={null}
cat ~/code/myproject/.git/hooks/post-commit
```

## Related Commands

* `repr generate` - Process queued commits into stories
* `repr repos pause/resume` - Control auto-tracking per repo
* `repr doctor` - Diagnose hook issues