git-ots/README.md

Git OpenTimestamp Hook

Automatically generate and manage OpenTimestamp proofs for git commits.

What It Does

• Post-commit hook: Creates cryptographic proof for every commit
• Pre-commit backfill: Upgrades historical proofs to Bitcoin-attested status
• Proof chaining: Links commits together for full history integrity
• Smart caching: Minimizes network calls after initial backfill

Proofs are stored in .ots/ and can be versioned alongside your code for tamper-evident history.

Quick Install

Recommended: Self-Contained Hooks

# Clone or download this skill
git clone <repository-url>
cd git-ots-hook

# Install both hooks (single command)
./hooks/install.sh /path/to/your/repo

# Commit the proofs
cd /path/to/your/repo
git add .ots/
git commit -m "Add OpenTimestamp proofs"

That's it! The hooks are now installed and will automatically timestamp every commit.

Legacy: Script-Based Installation

The older scripts/ directory is still available but deprecated. See SKILL.md for details.

Manual Installation

If you prefer to install hooks manually without the installer:

1. Copy Hook Files

cp hooks/post-commit /path/to/your/repo/.git/hooks/
cp hooks/pre-commit /path/to/your/repo/.git/hooks/
chmod +x /path/to/your/repo/.git/hooks/post-commit
chmod +x /path/to/your/repo/.git/hooks/pre-commit

2. Setup .gitignore

Add to your .gitignore:

.ots/.attestation-cache

3. Commit Initial Proofs

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

Prerequisites

Install the OpenTimestamp client:

# Recommended: Python CLI
pipx install opentimestamps-client

# Alternative: Node.js package
npm install -g @opentimestamps/ots

Verify installation:

ots --version

Generated Files

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

Verification

Verify a proof:

ots verify .ots/<commit-hash>.ots

Check attestation status:

./scripts/check-attestation.sh .ots/<commit-hash>.ots
# Output: "attested" or "pending"

How It Works

1. Commit created → Post-commit hook runs
2. Proof generated → ots stamp creates .ots file
3. Submitted to calendars → 4+ remote calendars receive hash
4. Bitcoin anchoring → Calendars batch and anchor to Bitcoin (~10 min)
5. Attestation → Proof becomes fully verifiable against Bitcoin blockchain

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

License

MIT

Links

• OpenTimestamp
• ots Client