Nerdbank.GitVersioning for Rust
This workspace contains:
nerdbank-gitversioning, a Rust library for calculating versions fromversion.json,version.txt, and Git history.nbgv, a command-line tool built on the library.
It supports Windows, Linux, and macOS and builds with current stable Rust (Rust 1.95 or later).
The Rust implementation targets compatibility with the non-MSBuild behavior of
the .NET implementation in this repository. It uses libgit2 in-process for
normal repository operations. If Git commit signing is enabled,
nbgv prepare-release may invoke the git executable to create signed commits.
Library usage
Add the library from this checkout:
[]
= { = "src/nerdbank-gitversioning-rs" }
Calculate a version from the repository containing the current directory:
use ;
CLI usage
Install the native CLI from this checkout:
cargo install --path src/nerdbank-gitversioning-rs/nbgv
nbgv get-version
Cargo installs nbgv.exe in %USERPROFILE%\.cargo\bin on Windows and
nbgv in $HOME/.cargo/bin on Linux and macOS. Add that directory to
PATH, if necessary.
The Rust CLI includes exactly the six commands that do not require MSBuild:
get-versioncalculates and prints version information.set-versionupdates the applicable version file.tagcreates a version tag.get-commitsfinds commits that produced a version.cloudsets cloud-build numbers and variables.prepare-releasecreates a release branch and updates versions.
Run nbgv --help or nbgv <command> --help for all options.
Preparing a release
ReleaseManager validates that the repository has an attached branch, a clean
working tree, a configured Git identity, and an applicable version file. It can
simulate a release, return text or JSON results, create and update the release
and development branches, and optionally merge the release branch. Version
files that inherit settings are edited without flattening their inheritance.
All ordinary repository work is performed in-process with libgit2. The git
executable is invoked only when commit.gpgSign is enabled, because libgit2
cannot create Git-compatible signed commits or merge commits.
Excluded .NET integration
The Rust packages do not provide MSBuild props, targets, tasks, generated
assembly metadata, or package installation. Consequently, the .NET tool's
install and path-filters commands are not included. Use the .NET nbgv
tool for those commands.
Development
Use current stable Rust:
cargo fmt --all --check
cargo clippy --workspace --all-targets --all-features -- -D warnings
cargo test --workspace
RUSTDOCFLAGS="-D warnings" cargo doc --workspace --no-deps
In PowerShell, set the documentation flags with
$env:RUSTDOCFLAGS = "-D warnings" before running cargo doc.
Benchmarks
Clone xunit, Cuemon, SuperSocket, and Nerdbank.GitVersioning under
%USERPROFILE%\Source\Repos on Windows or ~/git elsewhere, then run:
cargo bench --bench get_version
Set NBGV_BENCH_REPOSITORY_ROOT to use another directory. Missing repositories
produce an error. Criterion retains machine-readable results under
target/criterion.