Replace legacy scripts with separated ots/node hooks
- 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.
This commit is contained in:
Otto
parent
eec64d16c6
commit
b1e305d831
14 changed files with 484 additions and 616 deletions
163
SKILL.md
163
SKILL.md
|
|
@ -1,163 +1,128 @@
|
|||
---
|
||||
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. Supports both ots CLI and nodejs fallback.
|
||||
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 (Recommended)
|
||||
|
||||
**New: Self-contained hooks** - No external dependencies, simple installation:
|
||||
## Quick Start
|
||||
|
||||
```bash
|
||||
# Install both hooks (post-commit + pre-commit backfill)
|
||||
# Install both hooks (auto-detects ots CLI or Node.js)
|
||||
./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.
|
||||
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
|
||||
|
||||
- **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
|
||||
- **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`
|
||||
- Works with `ots` CLI (preferred) or `@opentimestamps/ots` node package (fallback)
|
||||
- **Self-contained**: No external script dependencies, simple drop-in installation
|
||||
- Smart caching: Skips calendar calls for recently checked proofs
|
||||
|
||||
## Prerequisites
|
||||
|
||||
Install one of:
|
||||
|
||||
**Option 1: ots CLI (Recommended - Full Bitcoin attestation)**
|
||||
```bash
|
||||
# Option 1: ots CLI (recommended)
|
||||
git clone https://github.com/opentimestamps/opentimestamps-client
|
||||
cd opentimestamps-client
|
||||
pipx install .
|
||||
pipx install opentimestamps-client
|
||||
```
|
||||
|
||||
# Option 2: Node.js fallback
|
||||
npm install -g @opentimestamps/ots
|
||||
**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
|
||||
|
||||
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
|
||||
│ ├── <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)
|
||||
└── ...
|
||||
```
|
||||
|
||||
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:**
|
||||
**Install hooks (auto-detect):**
|
||||
```bash
|
||||
./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:**
|
||||
**Manual installation:**
|
||||
```bash
|
||||
./scripts/generate-proof.sh <commit-hash> [output-file]
|
||||
# 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
|
||||
```
|
||||
|
||||
**Backfill proofs for entire history:**
|
||||
**Check attestation status:**
|
||||
```bash
|
||||
./scripts/backfill-proofs.sh /path/to/repo
|
||||
```
|
||||
|
||||
**Setup .gitignore (excludes cache only, keeps proofs):**
|
||||
```bash
|
||||
./scripts/setup-gitignore.sh /path/to/repo
|
||||
```
|
||||
|
||||
**Check proof attestation status:**
|
||||
```bash
|
||||
./scripts/check-attestation.sh .ots/<commit-hash>.ots
|
||||
# Output: "attested" or "pending"
|
||||
```
|
||||
|
||||
Example:
|
||||
```bash
|
||||
./scripts/generate-proof.sh abc123def456 .ots/proof.ots
|
||||
./scripts/backfill-proofs.sh .
|
||||
./scripts/setup-gitignore.sh .
|
||||
```
|
||||
|
||||
## Uninstall
|
||||
|
||||
```bash
|
||||
rm /path/to/repo/.git/hooks/post-commit
|
||||
ots info .ots/<commit-hash>.ots | grep -c "PendingAttestation"
|
||||
# 0 = attested, >0 = pending
|
||||
```
|
||||
|
||||
## Notes
|
||||
|
||||
### Versioning Proofs (Recommended)
|
||||
|
||||
To include proofs in your repository (recommended for tamper-evidence):
|
||||
### Versioning Proofs
|
||||
|
||||
```bash
|
||||
# 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`)
|
||||
**Commit these:**
|
||||
- `*.ots` - Individual proof per commit
|
||||
- `proof.ots` - Latest proof reference
|
||||
- `commit-chain.txt` - Full chain
|
||||
- `prev-commit.txt` - Previous commit link
|
||||
|
||||
**Recommended `.gitignore`:**
|
||||
```
|
||||
.ots/.attestation-cache
|
||||
```
|
||||
**Ignore these:**
|
||||
- `.attestation-cache` - Local performance cache
|
||||
- `node_modules/` - If using Node.js mode (auto-added by installer)
|
||||
|
||||
### 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
|
||||
- **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
|
||||
|
||||
### Other Notes
|
||||
### Modes
|
||||
|
||||
- Hook is silent if neither `ots` nor node package is found
|
||||
- Proofs become "attested" after ~10 min (Bitcoin confirmation)
|
||||
| Feature | ots CLI | Node.js |
|
||||
|---------|---------|---------|
|
||||
| Calendar submission | ✓ | ✗ |
|
||||
| Bitcoin attestation | ✓ | ✗ |
|
||||
| Local proofs | ✓ | ✓ |
|
||||
| Upgrade support | ✓ | ✗ |
|
||||
| Speed | Fast | Fast |
|
||||
|
||||
## Troubleshooting
|
||||
**Recommendation:** Use ots CLI for production. Node.js for development/testing only.
|
||||
|
||||
**Hook not running?**
|
||||
- Check it's executable: `chmod +x .git/hooks/post-commit`
|
||||
- Test manually: `.git/hooks/post-commit`
|
||||
## Uninstall
|
||||
|
||||
**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
|
||||
```bash
|
||||
rm .git/hooks/post-commit .git/hooks/pre-commit
|
||||
```
|
||||
|
|
|
|||
Loading…
Add table
Add a link
Reference in a new issue