948e7d9d70
- Rename post-commit-ots → post-commit - Rename pre-commit-ots → pre-commit - Remove legacy post-commit and pre-commit symlinks - Update install.sh and documentation - Simplified: only 2 hook files with standard names Hooks are now named exactly as git expects them, making manual installation more intuitive.
156 lines
4 KiB
Markdown
156 lines
4 KiB
Markdown
---
|
|
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)
|