---
name: git-ots-hook
description: Install and manage OpenTimestamp git hooks that generate cryptographic proof for every commit. Requires opentimestamps-client (ots CLI) for full Bitcoin attestation.
---

# Git OpenTimestamp Hook

Automatically generates OpenTimestamp proofs for git commits via git hooks.

## ⚠️ Prerequisites (Required)

**You must have `ots` CLI installed:**

```bash
# Recommended (isolated install)
pipx install opentimestamps-client

# Or with pip
pip install opentimestamps-client

# Or from source
git clone https://github.com/opentimestamps/opentimestamps-client
cd opentimestamps-client && pip install .
```

**Verify installation:**
```bash
ots --version
# v0.7.2 or later
```

> **Why ots CLI is required:** The Node.js `@opentimestamps/ots` package only creates local proofs without calendar submission or Bitcoin attestation. For tamper-evident timestamps anchored to Bitcoin, the Python `opentimestamps-client` is the only complete implementation.

## Quick Start

```bash
# Install both hooks (requires ots CLI)
./hooks/install.sh /path/to/repo

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

The installer will:
1. Verify `ots` CLI is installed
2. Install post-commit and pre-commit hooks
3. Setup `.gitignore` (excludes cache file)

## What It Does

- **Post-commit hook**: Generates `.ots/<commit-hash>.ots` for each new commit
- **Pre-commit backfill**: Upgrades historical proofs to Bitcoin-attested status
- Creates `.ots/proof.ots` (latest proof reference)
- Stores commit chain in `.ots/commit-chain.txt`
- Smart caching: Skips calendar calls for recently checked proofs
- Submits to 4+ remote calendar servers for Bitcoin anchoring

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

If you prefer manual setup:

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

Add to `.gitignore`:
```
.ots/.attestation-cache
```

## Manual Usage

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

**Verify a proof:**
```bash
ots verify .ots/<commit-hash>.ots
```

**Upgrade pending proofs:**
```bash
ots upgrade .ots/<commit-hash>.ots
```

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

### Performance

- **First backfill:** ~30-60s (scans history, contacts calendars)
- **Subsequent commits:** ~10-15s (cached status skips redundant calls)
- **Cache:** 1-hour validity, re-checks pending proofs after 10 min
- **Attestation time:** ~10 min (Bitcoin block confirmation)

### How It Works

1. **Commit created** → Post-commit hook runs
2. **Hash generated** → SHA256 of commit hash
3. **Submitted to calendars** → 4+ remote servers receive hash
4. **Bitcoin anchoring** → Calendars batch and anchor to Bitcoin
5. **Attestation** → `ots upgrade` downloads Bitcoin proof
6. **Verification** → Anyone can verify against Bitcoin blockchain

### Calendar Servers

Default calendars used:
- `https://a.pool.opentimestamps.org`
- `https://b.pool.opentimestamps.org`
- `https://a.pool.eternitywall.com`
- `https://btc.calendar.catallaxy.com`

## Uninstall

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

## Links

- [OpenTimestamp](https://opentimestamps.org/)
- [opentimestamps-client](https://github.com/opentimestamps/opentimestamps-client)
- [How OpenTimestamp works](https://petertodd.org/2016/opentimestamps-announcement)