hybrid-version

English | 简体中文

Hybrid Cargo.toml + Git version generation for Rust build.rs.

Generate comprehensive version constants and build fingerprints at compile time by merging Cargo.toml version metadata with Git repository state.

Features

• Hybrid version source — Reads major.minor.patch from Cargo.toml, combines with git branch, commit, and timestamp
• Auto-patch from commit count — When patch = 0, automatically counts commits since the version line was last changed (via git blame)
• Modified lines detection — Tracks both staged and unstaged changes, appends -D, -M{N} suffix
• Release safety — modified_cannot_build_release() panics in release mode if uncommitted changes exist
• Rich fingerprint output — Generates SOURCES_FINGERPRINT (version + branch + commit + commit time) and BUILD_FINGERPRINT (build time + toolchain)
• Build log — Writes timestamped build logs to avoid unnecessary rebuilds via cargo:rerun-if-changed
• Environment export — Export version string to shell via .env file or setx (Windows)
• Fluent API — Method chaining: Version::new(path)?.write_version(out)?.set_output_env("VAR")?.write_buildlog(log)?
• Git submodule support — Correctly handles nested git repositories
• No unsafe code — #![forbid(unsafe_code)]

Quick Start

1. Add as build dependency

[build-dependencies]
hybrid-version = "0.1.0"

2. Create build.rs

use hybrid_version::error::VResult;
use hybrid_version::version::Version;
use std::path::PathBuf;

fn main() -> VResult<()> {
    println!("cargo:rerun-if-changed=Cargo.toml");
    println!("cargo:rerun-if-changed=Buildlog.txt");

    let manifest_dir = std::env::var("CARGO_MANIFEST_DIR").unwrap();
    let out_dir = std::env::var("OUT_DIR").unwrap();

    Version::new(&manifest_dir)?
        .modified_cannot_build_release()
        .write_version(PathBuf::from(&out_dir).join("version.rs"))?;
    Ok(())
}

3. Use in your code

include!(concat!(env!("OUT_DIR"), "/version.rs"));

fn main() {
    println!("Version: {}", VERSION);
    println!("Source:  {}", SOURCES_FINGERPRINT);
    println!("Build:   {}", BUILD_FINGERPRINT);
}

Generated Constants

The generated version.rs provides these compile-time constants:

The VERSION string suffix indicates:

• -D — Debug build
• -M12 — Release build with 12 modified lines
• -D/M12 — Debug build with 12 modified lines

Version Public API

The Version struct is the core of hybrid-version. Its public fields and methods form the complete user-facing API.

Constructor

Chainable Methods

All methods consume and return Self, enabling fluent chaining:

Getter Methods

Usage Example

use hybrid_version::version::Version;

let ver = Version::new("/path/to/project")?;

println!("{}.{}.{}", ver.major(), ver.minor(), ver.patch()); // 0.5.3
println!("branch: {}, commit: {}", ver.branch(), ver.commit()); // main, 57181d0
println!("modified lines: {}", ver.modified()); // e.g. 12

Buildlog

To avoid unnecessary rebuilds, use write_buildlog with cargo:rerun-if-changed:

// build.rs
println!("cargo:rerun-if-changed=Buildlog.txt");
Version::new(&manifest_dir)?
    .write_buildlog("Buildlog.txt")?;

Build log example:

Why hybrid-version?

Unlike other git-version crates that derive versions solely from git tags or git describe, hybrid-version keeps your canonical version in Cargo.toml and enriches it with git metadata. This approach:

• Keeps Cargo.toml as the single source of truth for semantic version
• Automatically derives patch version from commit count (when patch=0)
• Generates rich fingerprints for debugging and traceability
• Prevents accidental release builds with uncommitted changes

Comparison

License

MIT