git-ots/SKILL.md

name	description
git-ots-hook	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:

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

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

./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:

./scripts/generate-proof.sh <commit-hash> [output-file]

Backfill proofs for entire history:

./scripts/backfill-proofs.sh /path/to/repo

Setup .gitignore (excludes cache only, keeps proofs):

./scripts/setup-gitignore.sh /path/to/repo

Check proof attestation status:

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

Example:

./scripts/generate-proof.sh abc123def456 .ots/proof.ots
./scripts/backfill-proofs.sh .
./scripts/setup-gitignore.sh .

Uninstall

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

Notes

Versioning Proofs (Recommended)

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

# 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