163 lines
4.3 KiB
Markdown
163 lines
4.3 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. 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:
|
|
|
|
```bash
|
|
# 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:
|
|
|
|
```bash
|
|
# 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:**
|
|
```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:**
|
|
```bash
|
|
./scripts/generate-proof.sh <commit-hash> [output-file]
|
|
```
|
|
|
|
**Backfill proofs for entire history:**
|
|
```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
|
|
```
|
|
|
|
## Notes
|
|
|
|
### Versioning Proofs (Recommended)
|
|
|
|
To include proofs in your repository (recommended for tamper-evidence):
|
|
|
|
```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`)
|
|
|
|
**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
|