---
name: git-ots-hook
description: Install and manage OpenTimestamp git hooks that generate cryptographic proof for every commit. Use when you need to add tamper-evident timestamps to git commits using the OpenTimestamp protocol. Auto-detects ots CLI (recommended) or Node.js package.
---

# Git OpenTimestamp Hook

Automatically generates OpenTimestamp proofs for git commits via git hooks.

## Quick Start

```bash
# Install both hooks (auto-detects ots CLI or Node.js)
./hooks/install.sh /path/to/repo

# Or from repo root
./hooks/install.sh .
```

The installer will:
1. Detect available tools (ots CLI preferred, Node.js fallback)
2. Install matching hooks
3. Setup `.gitignore` (excludes cache + node_modules)
4. Install `@opentimestamps/ots` locally if using Node.js mode

## What It Does

- **Auto-detects tools**: ots CLI (full Bitcoin attestation) or Node.js package (local proofs only)
- **Post-commit hook**: Generates `.ots/<commit-hash>.ots` for each new commit
- **Pre-commit backfill**: Upgrades historical proofs to attested status (ots CLI only)
- Creates `.ots/proof.ots` (latest proof reference)
- Stores commit chain in `.ots/commit-chain.txt`
- Smart caching: Skips calendar calls for recently checked proofs

## Prerequisites

**Option 1: ots CLI (Recommended - Full Bitcoin attestation)**
```bash
pipx install opentimestamps-client
```

**Option 2: Node.js (Local proofs only)**
```bash
# Package will be installed locally by the installer
# Or globally: npm install -g @opentimestamps/ots
```

## Generated Files

```
repo/
├── .ots/
│   ├── <commit-hash>.ots   # Individual proof per commit
│   ├── proof.ots           # Latest commit proof (reference)
│   ├── prev-commit.txt     # Previous commit hash (chaining)
│   ├── commit-chain.txt    # Full commit chain mapping
│   └── .attestation-cache  # Local cache (gitignore this)
└── ...
```

## Manual Usage

**Install hooks (auto-detect):**
```bash
./hooks/install.sh /path/to/repo
```

**Manual installation:**
```bash
# For ots CLI:
cp hooks/post-commit-ots .git/hooks/post-commit
cp hooks/pre-commit-ots .git/hooks/pre-commit

# For Node.js:
cp hooks/post-commit-node .git/hooks/post-commit
cp hooks/pre-commit-node .git/hooks/pre-commit

chmod +x .git/hooks/post-commit .git/hooks/pre-commit
```

**Check attestation status:**
```bash
ots info .ots/<commit-hash>.ots | grep -c "PendingAttestation"
# 0 = attested, >0 = pending
```

## Notes

### Versioning Proofs

```bash
git add .ots/
git commit -m "Add OpenTimestamp proofs"
```

**Commit these:**
- `*.ots` - Individual proof per commit
- `proof.ots` - Latest proof reference
- `commit-chain.txt` - Full chain
- `prev-commit.txt` - Previous commit link

**Ignore these:**
- `.attestation-cache` - Local performance cache
- `node_modules/` - If using Node.js mode (auto-added by installer)

### Performance

- **First backfill:** ~30-60s (scans history, contacts calendars)
- **Subsequent commits:** ~10-15s (cached status skips redundant calls)
- **Cache:** 1-hour validity, 10-min recheck for pending proofs

### Modes

| Feature | ots CLI | Node.js |
|---------|---------|---------|
| Calendar submission | ✓ | ✗ |
| Bitcoin attestation | ✓ | ✗ |
| Local proofs | ✓ | ✓ |
| Upgrade support | ✓ | ✗ |
| Speed | Fast | Fast |

**Recommendation:** Use ots CLI for production. Node.js for development/testing only.

## Uninstall

```bash
rm .git/hooks/post-commit .git/hooks/pre-commit
```