whogitit 1.0.0

# Core Concepts

Understanding these concepts will help you get the most out of whogitit.

## Line Attribution

whogitit tracks the origin of every line in your codebase. Each line is classified into one of five categories:

| Source | Symbol | Description |
|--------|--------|-------------|
| **AI** | `●` | Generated by AI and committed unchanged |
| **AIModified** | `◐` | Generated by AI, then edited by a human before commit |
| **Human** | `+` | Written by a human after AI edits in the same session |
| **Original** | `─` | Existed before the AI session started |
| **Unknown** | `?` | Attribution could not be determined |

### Why "AIModified" Matters

The distinction between `AI` and `AIModified` is crucial:

- **AI** (`●`): The AI wrote this and you accepted it as-is
- **AIModified** (`◐`): The AI wrote something, but you improved or corrected it

This helps identify code that was reviewed and refined versus code that was accepted wholesale.

## Three-Way Diff Analysis

whogitit uses a sophisticated three-way diff algorithm to accurately attribute lines, even when you modify AI-generated code before committing.

### The Three States

1. **Original** - The file content before any AI edits in this session
2. **AI Snapshot** - The file content after each AI edit
3. **Final** - The content at commit time

### How It Works

```text
Original Content          AI Generates           You Modify            Final Commit
      │                        │                      │                      │
      ▼                        ▼                      ▼                      ▼
┌──────────┐            ┌──────────┐            ┌──────────┐            ┌──────────┐
│ line 1   │            │ line 1   │            │ line 1   │            │ line 1   │
│ line 2   │     ──►    │ NEW LINE │     ──►    │ NEW LINE │     ──►    │ NEW LINE │ ● AI
│ line 3   │            │ line 2   │            │ EDITED   │            │ EDITED   │ ◐ AIModified
│          │            │ line 3   │            │ MY LINE  │            │ MY LINE  │ + Human
│          │            │          │            │ line 2   │            │ line 2   │ ─ Original
│          │            │          │            │ line 3   │            │ line 3   │ ─ Original
└──────────┘            └──────────┘            └──────────┘            └──────────┘
```

By comparing all three states, whogitit determines:
- Lines that appeared in AI snapshots and remained unchanged → `AI`
- Lines that appeared in AI snapshots but were modified → `AIModified`
- Lines you added that weren't in AI snapshots → `Human`
- Lines that existed before AI edits → `Original`

## Sessions and Prompts

### Sessions

A **session** represents a continuous period of working with an AI assistant. Each session has:

- **Session ID**: A unique identifier
- **Model**: The AI model used (e.g., `claude-opus-4-5-20251101`)
- **Start time**: When the session began
- **Prompts**: All the prompts used during the session

### Prompts

Each prompt you give to the AI is captured and stored with:

- **Index**: The order within the session (0, 1, 2, ...)
- **Text**: The actual prompt (with sensitive data redacted)
- **Affected files**: Which files were changed as a result

## Git Notes Storage

whogitit stores attribution data in **git notes**, a built-in git feature for attaching metadata to commits.

### Why Git Notes?

- **Native to git**: No external database required
- **Travels with the repo**: Notes can be pushed/fetched like branches
- **Non-invasive**: Doesn't modify commit history or clutter logs
- **Standard tooling**: Can be inspected with normal git commands

### The Notes Ref

Attribution is stored under `refs/notes/whogitit`:

```bash
# View raw attribution for a commit
git notes --ref=whogitit show HEAD

# List all commits with attribution
git notes --ref=whogitit list
```

## Pending Buffer

Before a commit, whogitit stores captured changes in a **pending buffer** (`.whogitit-pending.json`). This file:

- Accumulates all file edits during a session
- Stores complete content snapshots for three-way diff
- Is processed and cleared when you commit
- Can be cleared manually with `whogitit clear`

### Pending Buffer Lifecycle

```text
Claude Code Edit
       │
       ▼
PreToolUse Hook ──► Save "before" snapshot
       │
       ▼
   AI makes edit
       │
       ▼
PostToolUse Hook ──► Save "after" snapshot + prompt
       │
       ▼
.whogitit-pending.json (accumulates)
       │
       ▼ (git commit)
       │
Post-commit Hook ──► Three-way analysis ──► Git Note
       │
       ▼
Pending buffer cleared
```

## Privacy and Redaction

Prompts may contain sensitive information. whogitit automatically redacts:

- API keys and secrets
- AWS credentials
- Private keys
- Bearer tokens
- GitHub tokens
- Email addresses
- Passwords

See [Privacy & Redaction](../guide/privacy.md) for details on configuring redaction patterns.

## Next Steps

- Explore the [CLI Commands](../guide/cli-commands.md)
- Learn about [Configuration](../guide/configuration.md) options
- Understand the [Architecture](../reference/architecture.md) in depth