Macro git_testament::git_testament_macros

source · 
git_testament_macros!() { /* proc-macro */ }
Expand description

Generate a testament for the working tree as a set of static string macros.

This macro declares a set of macros which provide you with your testament as static strings.

The intention is that the macro should be used at the top level of a binary crate to provide information about the state of the codebase that the output program was built from. This includes a number of things such as the commit SHA, any related tag, how many commits since the tag, the date of the commit, and if there are any “dirty” parts to the working tree such as modified files, uncommitted files, etc.

// Bring the procedural macro into scope
use git_testament::git_testament_macros;

// Declare a testament, it'll end up as pile of macros, so you can
// give it whatever ident-like name you want.  The name will prefix the
// macro names.  Also you can optionally specify
// a branch name which will be considered the "trusted" branch like in
// `git_testament::render_testament!()`
git_testament_macros!(version);

// ... later, you can display the testament.
println!("app version {}", version_testament!());

The macros all resolve to string literals, boolean literals, or in the case of NAME_tag_distance!() a number. This is most valuable when you are wanting to include the information into a compile-time-constructed string

// Bring the procedural macro into scope
use git_testament::git_testament_macros;

// Declare a testament, it'll end up as pile of macros, so you can
// give it whatever ident-like name you want.  The name will prefix the
// macro names.  Also you can optionally specify
// a branch name which will be considered the "trusted" branch like in
// `git_testament::render_testament!()`
git_testament_macros!(version, "stable");

const APP_VERSION: &str = concat!("app version ", version_testament!());

// ... later, you can display the testament.
println!("{APP_VERSION}");

The set of macros defined is:

  • NAME_testament!() -> produces a string similar but not guaranteed to be identical to the result of Display formatting a normal testament.
  • NAME_branch!() -> An Option<&str> of the current branch name
  • NAME_repo_present!() -> A boolean indicating if there is a repo at all
  • NAME_commit_present!() -> A boolean indicating if there is a commit present at all
  • NAME_tag_present!() -> A boolean indicating if there is a tag present
  • NAME_commit_hash!() -> A string of the commit hash (or crate version if commit not present)
  • NAME_commit_date!() -> A string of the commit date (or build date if no commit present)
  • NAME_tag_name!() -> The tag name if present (or crate version if commit not present)
  • NAME_tag_distance!() -> The number of commits since the tag if present (zero otherwise)