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 KiB
Markdown
128 lines
3 KiB
Markdown
# Git OpenTimestamp Hook
|
|
|
|
Automatically generate and manage [OpenTimestamp](https://opentimestamps.org/) 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
|
|
|
|
```bash
|
|
# Clone or download this skill
|
|
git clone <repository-url>
|
|
cd git-ots-hook
|
|
|
|
# Install both hooks (auto-detects ots CLI or Node.js)
|
|
./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.
|
|
|
|
## Manual Installation
|
|
|
|
### For ots CLI (Recommended)
|
|
|
|
```bash
|
|
cp hooks/post-commit-ots .git/hooks/post-commit
|
|
cp hooks/pre-commit-ots .git/hooks/pre-commit
|
|
chmod +x .git/hooks/post-commit .git/hooks/pre-commit
|
|
```
|
|
|
|
### For Node.js (Local proofs only)
|
|
|
|
```bash
|
|
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
|
|
```
|
|
|
|
### Setup .gitignore
|
|
|
|
```
|
|
.ots/.attestation-cache
|
|
node_modules/
|
|
```
|
|
|
|
### Commit Initial Proofs
|
|
|
|
```bash
|
|
git add .ots/
|
|
git commit -m "Add OpenTimestamp proofs"
|
|
```
|
|
|
|
## Prerequisites
|
|
|
|
Install the OpenTimestamp client:
|
|
|
|
```bash
|
|
# Recommended: Python CLI
|
|
pipx install opentimestamps-client
|
|
|
|
# Alternative: Node.js package
|
|
npm install -g @opentimestamps/ots
|
|
```
|
|
|
|
Verify installation:
|
|
```bash
|
|
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:
|
|
```bash
|
|
ots verify .ots/<commit-hash>.ots
|
|
```
|
|
|
|
Check attestation status:
|
|
```bash
|
|
./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](https://opentimestamps.org/)
|
|
- [ots Client](https://github.com/opentimestamps/opentimestamps-client)
|