.nornir/version-scheme-design.md

Version + git-hash scheme

Holger stamps every build with its version and the exact commit it was built from, and surfaces one identical identity string everywhere — so an operator staring at a --version line, a health probe, and an About readout can never be looking at three different answers.

The string

holger v<CARGO_PKG_VERSION> (<git-hash>)

e.g. holger v0.6.9 (7c79dfe). <git-hash> is the 7-char short sha of the commit the binary was built from (or unknown when built without git metadata, e.g. from a source tarball).

Single source of truth

The string is built once, at compile time, in holger-server-lib:

// server/lib/src/lib.rs
pub const GIT_HASH: &str = env!("HOLGER_GIT_HASH");
pub const VERSION_LINE: &str =
    concat!("holger v", env!("CARGO_PKG_VERSION"), " (", env!("HOLGER_GIT_HASH"), ")");

Every surface reads server_lib::VERSION_LINE — they cannot drift:

Surface	Where
Server bins `--version` / `-V`	`server/cli/src/main.rs` (all `holger-*` bins share `main.rs`)
gRPC `Health.version`	`server/lib/src/grpc/services.rs`
In-process `LocalHolger::health().version`	`server/lib/src/object.rs`
Agent bin `holger-agent --version`	`agent/cli/src/main.rs` — carries its OWN stamp (below)

The agent CLI stamps itself

The airgap agent (holger-agent) runs internet-side and must NOT path-dep the whole holger-server-lib just to read VERSION_LINE. A build script exports its env only to its own crate, so the agent carries a self-contained copy of the same pure-FS git-hash logic in agent/cli/build.rs, emitting HOLGER_AGENT_GIT_HASH, and its clap command sets version = concat!("v", CARGO_PKG_VERSION, " (", hash, ")") so holger-agent --version prints holger-agent v<ver> (<git-hash>) — the same v<ver> (<hash>) shape as the server, satisfying build-version-githash-law for every shipping bin, not just the server family.

Where the hash comes from — pure-Rust `build.rs`

server/lib/build.rs derives the hash without ever shelling out (the pure-rust-zero-shell-law: no git, no std::process::Command). It reads the on-disk git plumbing with std::fs and emits:

cargo:rustc-env=HOLGER_GIT_HASH=<short sha>

Resolution order (each step degrades gracefully — the build never fails, it falls back to unknown):

Locate the git dir by walking up from CARGO_MANIFEST_DIR: a real .git/ directory, or a .git file (gitdir: …) as used by linked worktrees (whose refs/packed-refs live in the shared commondir).
Read HEAD. A ref: refs/heads/… line is followed to the loose ref file (checked in both the worktree git dir and the common dir), then falls back to packed-refs. A bare 40-hex HEAD is a detached checkout and is used as-is.
Emit HOLGER_GIT_HASH plus a cargo:rerun-if-changed for every file consulted (HEAD, the loose ref, packed-refs) so the stamp is rebuilt the moment you commit or switch branches.

`--version` behaviour

--version / -V is handled manually at the very top of main() — before logger init, config load, or any boot — and prints VERSION_LINE then exits 0. It is done by hand (clap has no version set on the command) precisely so every holger-* server bin prints the SAME string the health surfaces report.

$ holger-server --version
holger v0.6.9 (7c79dfe)
$ holger-mvp -V
holger v0.6.9 (7c79dfe)