What Are Refs?
Refs (references) in SHM are a powerful mechanism for managing document relationships. They're similar to Git refs — pointers that can branch, redirect, or mark documents as deleted. Refs enable open collaboration where anyone can fork, improve, and share content while preserving attribution.
Types of Refs
Version Refs (Branches)
A version ref creates a fork of an existing document. Your copy starts from the forked version and you can make independent edits while the original attribution is preserved.
# Fork a document to your own account
grpcurl -plaintext -d '{
"signing_key_name": "mykey",
"account": "z6MkMYACCOUNT...",
"path": "/my-fork",
"target": {
"account": "z6MkORIGINAL...",
"path": "/original-doc",
"version": "bafy2bz..."
}
}' localhost:55002 \
com.seed.documents.v3alpha.Documents/CreateRefAfter creating a version ref, you can edit your fork independently. Others can see it was forked from the original, creating a transparent provenance chain.
Redirect Refs
Redirect refs point one path to another document. This is useful for URL management — if you restructure your content, you can redirect old paths to new locations.
# Create a redirect from /old-path to /new-path
grpcurl -plaintext -d '{
"signing_key_name": "mykey",
"account": "z6Mk...",
"path": "/old-path",
"target": {
"account": "z6Mk...",
"path": "/new-path"
}
}' localhost:55002 \
com.seed.documents.v3alpha.Documents/CreateRefRedirects are transparent — the web UI shows the target document while preserving the original URL for bookmarks and links.
Tombstone Refs
Tombstone refs mark a document as deleted. Since SHM content is cryptographically signed and content-addressed, you can't truly delete distributed content. Instead, tombstones signal that the author considers the content removed.
Gateways and well-behaved clients respect tombstones by hiding the content.
Branching via CLI
The ion-hm CLI provides convenient commands for branching:
# Fork a document
ion-hm branch mykey \
"hm://z6MkOriginal.../source-doc" \
"/my-fork-path"
# Create a redirect
ion-hm redirect mykey \
"/old-path" \
"hm://z6Mk.../new-path"
# Get info about a ref
ion-hm ref-info <ref-id>Collaboration Model
SHM's branching enables a unique collaboration model:
1. Alice publishes a document
2. Bob forks it using a version ref — his fork attributes back to Alice's original
3. Bob makes improvements and publishes his version
4. Alice can see Bob's fork and choose to incorporate his changes
5. Carol can fork from either Alice or Bob, creating a tree of versions
This is like GitHub's fork model but for documents, with cryptographic attribution at every level.
Direct Write Access
Instead of forking, an account owner can grant direct write access using capabilities:
# Grant write access to a collaborator
grpcurl -plaintext -d '{
"signing_key_name": "mykey",
"delegate": "z6MkCOLLABORATOR...",
"account": "z6MkMYACCOUNT...",
"path": "/shared-project",
"role": "WRITER"
}' localhost:55002 \
com.seed.documents.v3alpha.AccessControl/CreateCapabilityWith WRITER access, the collaborator can edit documents directly under the specified path. Their changes are signed with their own key but published under the account owner's namespace.
Version Pinning
When embedding or referencing other documents, you can pin to a specific version:
# Reference with version pinning
hm://z6Mk.../document?v=bafy2bz...
# Without version - always shows latest
hm://z6Mk.../documentVersion pinning is important for citations and references where you want to point to exactly what you saw, not whatever the author might change later.
Practical Use Cases
• Wiki-style collaboration — Fork articles, improve them, track provenance
• URL management — Redirect old paths when restructuring content
• Content curation — Fork and annotate others' content while preserving attribution
• Soft deletion — Tombstone content you want to retract
• Translation — Fork a document, translate it, and link back to the original
• Archiving — Create version refs to snapshot important documents at specific points in time