shasha
Shasha is an external Git command that creates self-identifying commits.
When Shasha creates a commit, it writes an abbreviated form of that commit's
object ID to .shasha inside the same commit. With the default six-character
prefix, the result has this invariant:
$ git show HEAD:.shasha
7e3a1f
$ git rev-parse HEAD
7e3a1f4...
The value stored in .shasha is a prefix, not the complete object ID. The full
object ID remains Git's authoritative identifier.
Why?
Builds often need a revision they can display at runtime, even when the .git
directory is unavailable. CI can inject that value, but a tracked file also
travels naturally through source archives, container build contexts, and copied
working trees.
Writing a commit's object ID into a tracked file appears circular: changing the
file changes the tree, which changes the commit. Shasha turns that circularity
into a finite search. It places a candidate prefix in .shasha, varies a nonce
inside the commit, and stops when the resulting object ID begins with the same
prefix.
Quick start
Install the extension from crates.io:
For an ordinary commit of already-staged changes, use git shasha -m in place
of git commit -m:
$ git add src/
$ git shasha -m "Add the landing page"
[main 7e3a1f] Add the landing page
mined 9342012 candidates in 52.0ms (179.7 MH/s)
.shasha contains 7e3a1f; full commit is 7e3a1f4...
No Git alias, hook, or patched Git installation is required.
Why git shasha works
Git has a standard mechanism for external commands. When it receives an unknown
subcommand, it looks for an executable named git-<subcommand> on PATH:
git shasha -m "Message"
└── executes git-shasha -m "Message"
The Shasha package therefore installs two executables:
git-shasha: the Git extension, invoked asgit shasha;shasha: a standalone compatibility command with identical behavior.
git shasha is the canonical interface. After installation, these commands
should succeed:
Cargo normally installs executables in ~/.cargo/bin. That directory must be
on PATH so Git can discover git-shasha.
Commit workflow
Shasha supports a subset of git commit's index-based workflow. For an
ordinary commit, stage changes first and provide the message with -m or -F:
Only already-staged changes are committed, with one exception: Shasha generates
and force-adds .shasha, even when an ignore rule matches it. The file is meant
to be tracked and updated by every commit created with Shasha.
Running an ordinary git commit does not invoke Shasha and does not update
.shasha. Shasha is currently a separate commit implementation, not a wrapper
around git commit and not a pre-commit hook.
Shasha does not pass command-line options through to git commit, because it
does not invoke git commit. Unsupported options such as --amend, -a,
--author, --signoff, --allow-empty, and -S are rejected rather than
silently ignored.
Multiple -m arguments create separate message paragraphs:
A message can also come from a file or standard input:
|
Supported Shasha options:
-m, --message <MESSAGE> Commit message; repeat to create paragraphs
-F, --file <PATH> Read the commit message from a file, or '-' for stdin
--sha-file <PATH> Version file relative to the repository root [default: .shasha]
--length <N> Number of hexadecimal prefix characters to mine [default: 6]
--threads <N> Mining threads [default: available parallelism]
Status and limitations
Shasha is an early, working implementation. Use it on repositories whose history you can recover until the project has had wider review.
Currently supported:
- SHA-1 and SHA-256 Git repositories;
- initial and ordinary single-parent commits;
- staged changes;
- configurable prefix length, output file, and worker count;
- linked worktrees and packed refs;
- atomic branch and detached-HEAD updates.
Shasha currently refuses to run during merges, rebases, cherry-picks, and reverts. It does not run Git commit hooks and does not create signed commits. Sign an annotated tag if the resulting revision needs a signature.
The result is otherwise a normal Git commit: Git stores it, verifies it, and addresses it by its complete object ID.
How it works
Shasha first chooses a target prefix and writes it to .shasha. It then asks
Git to create the staged tree. That fixes the tree ID, parent, identities,
timestamps, and commit message except for a fixed-width trailer:
Shasha-Nonce: 00000000000f28a3
Workers vary this nonce and hash candidate commit objects in memory. Shasha
publishes a commit only after finding an object ID that starts with the value
already placed in .shasha.
Before moving HEAD, Shasha recomputes the winning object through an independent
digest path and stores a standard Git commit object. It updates the current ref
with git update-ref, using the previous object ID as an atomic compare-and-swap
guard.
The mining loop does not launch a Git process for every candidate. It pre-compresses the constant hash blocks, changes only the final block for each fixed-width nonce, and uses all available CPU workers by default. On AArch64 processors it detects and uses the ARMv8 SHA instructions at runtime; other CPUs use the portable RustCrypto backend.
Prefix length and cost
The default prefix is six hexadecimal characters, or 24 bits. It takes 16,777,216 candidate hashes on average. Each additional character multiplies the expected work by 16.
| Characters | Expected candidates |
|---|---|
| 4 | 65,536 |
| 5 | 1,048,576 |
| 6 | 16,777,216 |
| 7 | 268,435,456 |
| 8 | 4,294,967,296 |
Six characters are convenient but not globally unique. Shasha avoids a prefix already used by an object at creation time, but a future object can still acquire the same prefix. Git may then require more characters to disambiguate the revision; the full object ID remains authoritative.
Development
Build without installing and expose the development binary to Git:
PATH="/target/debug:"
Run the complete local checks:
Integration tests create temporary SHA-1 and, when supported by the installed
Git, SHA-256 repositories. They cover the actual git shasha dispatch, packed
objects and refs, linked worktrees, and validate resulting object graphs with
git fsck --strict.
License
MIT. See LICENSE.