Struct Gitcl 

pub struct Gitcl { /* private fields */ }

The VERGEN_GIT_* configuration features

Variable	Sample
VERGEN_GIT_BRANCH	feature/fun
VERGEN_GIT_COMMIT_AUTHOR_EMAIL	janedoe@email.com
VERGEN_GIT_COMMIT_AUTHOR_NAME	Jane Doe
VERGEN_GIT_COMMIT_COUNT	330
VERGEN_GIT_COMMIT_DATE	2021-02-24
VERGEN_GIT_COMMIT_MESSAGE	feat: add commit messages
VERGEN_GIT_COMMIT_TIMESTAMP	2021-02-24T20:55:21+00:00
VERGEN_GIT_DESCRIBE	5.0.0-2-gf49246c
VERGEN_GIT_SHA	f49246ce334567bff9f950bfd0f3078184a2738a
VERGEN_GIT_DIRTY	true

Example

Emit all of the git instructions

let gitcl = GitclBuilder::all_git()?;
Emitter::default().add_instructions(&gitcl)?.emit()?;

Emit some of the git instructions

let gitcl = GitclBuilder::default().describe(true, false, None).build()?;
Emitter::default().add_instructions(&gitcl)?.emit()?;

Override output with your own value

temp_env::with_var("VERGEN_GIT_BRANCH", Some("this is the branch I want output"), || {
    let result = || -> Result<()> {
        let gitcl = GitclBuilder::all_git()?;
        Emitter::default().add_instructions(&gitcl)?.emit()?;
        Ok(())
    }();
    assert!(result.is_ok());
});

Example

This feature can also be used in conjuction with the SOURCE_DATE_EPOCH environment variable to generate deterministic timestamps based off the last modification time of the source/package

temp_env::with_var("SOURCE_DATE_EPOCH", Some("1671809360"), || {
    let result = || -> Result<()> {
        let gitcl = GitclBuilder::all_git()?;
        Emitter::default().add_instructions(&gitcl)?.emit()?;
        Ok(())
    }();
    assert!(result.is_ok());
});

The above will always generate the following output for the timestamp related instructions

...
cargo:rustc-env=VERGEN_GIT_COMMIT_DATE=2022-12-23
...
cargo:rustc-env=VERGEN_GIT_COMMIT_TIMESTAMP=2022-12-23T15:29:20.000000000Z
...

Example

This feature also recognizes the idempotent flag.

NOTE - SOURCE_DATE_EPOCH takes precedence over the idempotent flag. If you use both, the output will be based off SOURCE_DATE_EPOCH. This would still be deterministic.

Example

let gitcl = GitclBuilder::all_git()?;
Emitter::default().idempotent().add_instructions(&gitcl)?.emit()?;

The above will always generate the following instructions

cargo:rustc-env=VERGEN_GIT_BRANCH=VERGEN_IDEMPOTENT_OUTPUT
cargo:rustc-env=VERGEN_GIT_COMMIT_AUTHOR_EMAIL=VERGEN_IDEMPOTENT_OUTPUT
cargo:rustc-env=VERGEN_GIT_COMMIT_AUTHOR_NAME=VERGEN_IDEMPOTENT_OUTPUT
cargo:rustc-env=VERGEN_GIT_COMMIT_COUNT=VERGEN_IDEMPOTENT_OUTPUT
cargo:rustc-env=VERGEN_GIT_COMMIT_DATE=VERGEN_IDEMPOTENT_OUTPUT
cargo:rustc-env=VERGEN_GIT_COMMIT_MESSAGE=VERGEN_IDEMPOTENT_OUTPUT
cargo:rustc-env=VERGEN_GIT_COMMIT_TIMESTAMP=VERGEN_IDEMPOTENT_OUTPUT
cargo:rustc-env=VERGEN_GIT_DESCRIBE=VERGEN_IDEMPOTENT_OUTPUT
cargo:rustc-env=VERGEN_GIT_SHA=VERGEN_IDEMPOTENT_OUTPUT
cargo:warning=VERGEN_GIT_BRANCH set to default
cargo:warning=VERGEN_GIT_COMMIT_AUTHOR_EMAIL set to default
cargo:warning=VERGEN_GIT_COMMIT_AUTHOR_NAME set to default
cargo:warning=VERGEN_GIT_COMMIT_COUNT set to default
cargo:warning=VERGEN_GIT_COMMIT_DATE set to default
cargo:warning=VERGEN_GIT_COMMIT_MESSAGE set to default
cargo:warning=VERGEN_GIT_COMMIT_TIMESTAMP set to default
cargo:warning=VERGEN_GIT_DESCRIBE set to default
cargo:warning=VERGEN_GIT_SHA set to default
cargo:rerun-if-changed=build.rs
cargo:rerun-if-env-changed=VERGEN_IDEMPOTENT
cargo:rerun-if-env-changed=SOURCE_DATE_EPOCH

Implementations

impl Gitcl

pub fn at_path(&mut self, path: PathBuf) -> &mut Self

Run at the given path

pub fn git_cmd(&mut self, cmd: Option<&'static str>) -> &mut Self

Set the command used to test if git exists on the path. Defaults to git --version if not set explicitly.

Trait Implementations

impl Add for Gitcl

fn add_map_entries( &self, idempotent: bool, cargo_rustc_env: &mut CargoRustcEnvMap, cargo_rerun_if_changed: &mut CargoRerunIfChanged, cargo_warning: &mut CargoWarning, ) -> Result<()>

Try to add instructions entries to the various given arguments.

fn add_default_entries( &self, config: &DefaultConfig, cargo_rustc_env_map: &mut CargoRustcEnvMap, cargo_rerun_if_changed: &mut CargoRerunIfChanged, cargo_warning: &mut CargoWarning, ) -> Result<()>

Based on the given configuration, emit either default idempotent output or generate a failue.

impl Clone for Gitcl

fn clone(&self) -> Gitcl

Returns a duplicate of the value.

fn clone_from(&mut self, source: &Self)

Performs copy-assignment from source.

impl Debug for Gitcl

fn fmt(&self, f: &mut Formatter<'_>) -> Result

Formats the value using the given formatter.

impl PartialEq for Gitcl

fn eq(&self, other: &Gitcl) -> bool

Tests for self and other values to be equal, and is used by ==.

fn ne(&self, other: &Rhs) -> bool

Tests for !=. The default implementation is almost always sufficient, and should not be overridden without very good reason.

impl StructuralPartialEq for Gitcl