b1e305d831
- Remove deprecated scripts/ directory (6 files) - Add hooks/post-commit-ots (ots CLI version) - Add hooks/pre-commit-ots (ots CLI backfill) - Add hooks/post-commit-node (Node.js version, local proofs only) - Add hooks/pre-commit-node (Node.js backfill, no upgrade) - Update hooks/install.sh to auto-detect and install matching hooks - Update documentation (SKILL.md, README.md, AGENTS.md) - Add node_modules/ to .gitignore for Node.js mode Breaking change: Scripts removed, use new hooks/ directory.
128 lines
3.4 KiB
Markdown
128 lines
3.4 KiB
Markdown
---
|
|
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. Auto-detects ots CLI (recommended) or Node.js package.
|
|
---
|
|
|
|
# Git OpenTimestamp Hook
|
|
|
|
Automatically generates OpenTimestamp proofs for git commits via git hooks.
|
|
|
|
## Quick Start
|
|
|
|
```bash
|
|
# Install both hooks (auto-detects ots CLI or Node.js)
|
|
./hooks/install.sh /path/to/repo
|
|
|
|
# Or from repo root
|
|
./hooks/install.sh .
|
|
```
|
|
|
|
The installer will:
|
|
1. Detect available tools (ots CLI preferred, Node.js fallback)
|
|
2. Install matching hooks
|
|
3. Setup `.gitignore` (excludes cache + node_modules)
|
|
4. Install `@opentimestamps/ots` locally if using Node.js mode
|
|
|
|
## What It Does
|
|
|
|
- **Auto-detects tools**: ots CLI (full Bitcoin attestation) or Node.js package (local proofs only)
|
|
- **Post-commit hook**: Generates `.ots/<commit-hash>.ots` for each new commit
|
|
- **Pre-commit backfill**: Upgrades historical proofs to attested status (ots CLI only)
|
|
- Creates `.ots/proof.ots` (latest proof reference)
|
|
- Stores commit chain in `.ots/commit-chain.txt`
|
|
- Smart caching: Skips calendar calls for recently checked proofs
|
|
|
|
## Prerequisites
|
|
|
|
**Option 1: ots CLI (Recommended - Full Bitcoin attestation)**
|
|
```bash
|
|
pipx install opentimestamps-client
|
|
```
|
|
|
|
**Option 2: Node.js (Local proofs only)**
|
|
```bash
|
|
# Package will be installed locally by the installer
|
|
# Or globally: npm install -g @opentimestamps/ots
|
|
```
|
|
|
|
## 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 Usage
|
|
|
|
**Install hooks (auto-detect):**
|
|
```bash
|
|
./hooks/install.sh /path/to/repo
|
|
```
|
|
|
|
**Manual installation:**
|
|
```bash
|
|
# For ots CLI:
|
|
cp hooks/post-commit-ots .git/hooks/post-commit
|
|
cp hooks/pre-commit-ots .git/hooks/pre-commit
|
|
|
|
# For Node.js:
|
|
cp hooks/post-commit-node .git/hooks/post-commit
|
|
cp hooks/pre-commit-node .git/hooks/pre-commit
|
|
|
|
chmod +x .git/hooks/post-commit .git/hooks/pre-commit
|
|
```
|
|
|
|
**Check attestation status:**
|
|
```bash
|
|
ots info .ots/<commit-hash>.ots | grep -c "PendingAttestation"
|
|
# 0 = attested, >0 = pending
|
|
```
|
|
|
|
## 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
|
|
- `node_modules/` - If using Node.js mode (auto-added by installer)
|
|
|
|
### 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
|
|
|
|
### Modes
|
|
|
|
| Feature | ots CLI | Node.js |
|
|
|---------|---------|---------|
|
|
| Calendar submission | ✓ | ✗ |
|
|
| Bitcoin attestation | ✓ | ✗ |
|
|
| Local proofs | ✓ | ✓ |
|
|
| Upgrade support | ✓ | ✗ |
|
|
| Speed | Fast | Fast |
|
|
|
|
**Recommendation:** Use ots CLI for production. Node.js for development/testing only.
|
|
|
|
## Uninstall
|
|
|
|
```bash
|
|
rm .git/hooks/post-commit .git/hooks/pre-commit
|
|
```
|