---
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. Supports both ots CLI and nodejs fallback.
---

# Git OpenTimestamp Hook

Automatically generates OpenTimestamp proofs for git commits via git hooks.

## Quick Start (Recommended)

**New: Self-contained hooks** - No external dependencies, simple installation:

```bash
# Install both hooks (post-commit + pre-commit backfill)
./hooks/install.sh /path/to/repo

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

## Legacy Installation

The older `scripts/` directory is still available for backward compatibility, but the new `hooks/` directory is recommended for simpler deployment.

## What It Does

- **Post-commit hook** (`hooks/post-commit`): Generates `.ots/<commit-hash>.ots` for each new commit
- **Pre-commit backfill** (`hooks/pre-commit`): Before each commit, upgrades all historical proofs to attested status
- Creates `.ots/proof.ots` with latest commit proof
- Stores commit chain in `.ots/commit-chain.txt`
- Works with `ots` CLI (preferred) or `@opentimestamps/ots` node package (fallback)
- **Self-contained**: No external script dependencies, simple drop-in installation

## Prerequisites

Install one of:

```bash
# Option 1: ots CLI (recommended)
git clone https://github.com/opentimestamps/opentimestamps-client
cd opentimestamps-client
pipx install .

# Option 2: Node.js fallback
npm install -g @opentimestamps/ots
```

## Generated Files

The hooks create:

```
repo/
├── .ots/
│   ├── proof.ots           # Timestamp proof for latest commit
│   ├── <commit-hash>.ots   # Individual proof for each commit
│   ├── prev-commit.txt     # Previous commit hash (for chaining)
│   └── commit-chain.txt    # Full commit chain mapping
└── ...
```

Proof files include:
- Commit hash timestamp (OpenTimestamp format)
- Bitcoin attestation (after ~10 min confirmation)
- Commit chain references

## Manual Usage

### New Self-Contained Hooks (Recommended)

**Install hooks:**
```bash
./hooks/install.sh /path/to/repo
```

**Manual hook installation:**
Copy `hooks/post-commit` and `hooks/pre-commit` directly to `.git/hooks/`

### Legacy Scripts (Deprecated)

**Generate proof for a specific commit:**
```bash
./scripts/generate-proof.sh <commit-hash> [output-file]
```

**Backfill proofs for entire history:**
```bash
./scripts/backfill-proofs.sh /path/to/repo
```

**Setup .gitignore (excludes cache only, keeps proofs):**
```bash
./scripts/setup-gitignore.sh /path/to/repo
```

**Check proof attestation status:**
```bash
./scripts/check-attestation.sh .ots/<commit-hash>.ots
# Output: "attested" or "pending"
```

Example:
```bash
./scripts/generate-proof.sh abc123def456 .ots/proof.ots
./scripts/backfill-proofs.sh .
./scripts/setup-gitignore.sh .
```

## Uninstall

```bash
rm /path/to/repo/.git/hooks/post-commit
```

## Notes

### Versioning Proofs (Recommended)

To include proofs in your repository (recommended for tamper-evidence):

```bash
# Commit proofs with your code
git add .ots/
git commit -m "Add OpenTimestamp proofs"
```

The `.ots/` directory contains:
- `*.ots` - Binary proof files (commit these)
- `commit-chain.txt` - Commit chain mapping (commit this)
- `prev-commit.txt` - Latest previous commit (commit this)
- `.attestation-cache` - Local cache (add to `.gitignore`)

**Recommended `.gitignore`:**
```
.ots/.attestation-cache
```

### Performance

- **Pre-commit backfill** can slow down commits on large histories
- First backfill: Full scan + calendar calls (~30-60s)
- Subsequent commits: Cached status skips calendar calls (~10-15s)
- Cache expires after 1 hour, re-checks pending proofs after 10 min

### Other Notes

- Hook is silent if neither `ots` nor node package is found
- Proofs become "attested" after ~10 min (Bitcoin confirmation)

## Troubleshooting

**Hook not running?**
- Check it's executable: `chmod +x .git/hooks/post-commit`
- Test manually: `.git/hooks/post-commit`

**Proof not generating?**
- Verify `ots` or `@opentimestamps/ots` is installed
- Check hook output: `git commit` shows `[ots]` messages

**Want auto-commit proofs?**
- Modify the hook to run `git add .ots/proof.ots && git commit --amend --no-edit`
- ⚠️ This changes commit history - use with caution