From ef05c84fb000211861dc8b44a3c6008f79c05e1b Mon Sep 17 00:00:00 2001 From: Alessandro Bertulli Date: Wed, 5 Nov 2025 21:40:08 +0100 Subject: [PATCH 1/2] Add API documentation --- README.md | 23 ++++++++++++++++++++++- 1 file changed, 22 insertions(+), 1 deletion(-) diff --git a/README.md b/README.md index 2181aed..1c792be 100644 --- a/README.md +++ b/README.md @@ -24,7 +24,7 @@ target_link_libraries(your_target cmake_git_version_tracking ) ``` -Then [`#include git.h`](./git.h) and use the provided functions to retrieve git metadata. +Then [`#include "git.h"`](./git.h) and use the provided functions to retrieve git metadata. ## Intended use case You're continuously shipping prebuilt binaries for an @@ -40,6 +40,27 @@ Dirty: false (there were no uncommitted changes at time of build) This allows you to investigate the _precise_ version of the application that the bug was reported in. +## API reference +This CMake module exports both a C and a C++ API. Both are accessed by including ["git.h"](./git.h). Here is the list of functions you can +call after including the module. + +| Description | C API | C++ API[^1] | Output | Git command | +| ----------- | ----- | ---------- | ------ | ----------- | +| Check if repo is correctly configured | `bool git_IsPopulated()` | `bool git::IsPopulated()` | `true`/`false` | (Set to `0` if git commands signal an error) | +| Check if the worktree is dirty (there are uncommited changes)[^2] | `bool git_AnyUncommittedChanges()` | `bool git::AnyUncommittedChanges()` | `true`/`false` | `git status --porcelain -unormal` | +| Get the author's name | 
const char* git_AuthorName()
| `const StringOrView& git::AuthorName()` | `"Andrew Hardin"` | `git show -s "--format=%an"` | +| Get the author's email | const char* git_AuthorEmail() | `const StringOrView& git::AuthorEmail()` | `"andrew.hardin@github.com"` | `git show -s "--format=%ae"` | +| Get the commit full SHA1 ID | 
const char* git_CommitSHA1()
| `const StringOrView& git::CommitSHA1()` | `"815da8c5a326f10931c0ce5944c62da11bbe784e"` | `git show -s "--format=%H"` | +| Get the commit date | 
const char* git_CommitDate()
 | `const StringOrView& git::CommitDate()` | `"2025-11-05 17:01:07 +0100"` | `git show -s "--format=%ci"` | +| Get the commit subject | `const char* git_CommitSubject()` | `const StringOrView& git::CommitSubject()` | `"An example commit subject"` | `git show -s "--format=%s"` | +| Get the commit full body | `const char* git_CommitBody()` | `const StringOrView& git::CommitBody()` | `"An example commit body\nthat can span multiple lines"`[^3] | `git show -s "--format=%b"` | +| Get the commit describe string | `const char* git_Describe()` | `const StringOrView& git::Describe()` | `"v1.0.2-5g815da8c"` | `git describe --always` | +| Get the current branch | `const char* git_Branch()` | `const StringOrView& git::Branch()` | `"main"` | `git symbolic-ref --short -q` | + +[^1]: The `StringOrView` type is an alias to `std::string`. By setting the configuration variable `GIT_VERSION_USE_STRING_VIEW` to true, it becomes an alias to `std::string_view`. +[^2]: By default, it considers untracked files as a dirty worktree. By setting the configuration variable `GIT_IGNORE_UNTRACKED` to true, it ignores them and only considers tracked modified files. +[^3]: The returned string has whitespace automatically escaped (it will contain printable sequences `"\n"` and `"\r"`) + ## Q: What if I want to track `$special_git_field`? Fork the project and modify [git_watcher.cmake](git_watcher.cmake) to track new additional fields (e.g. kernel version or build hostname). From 91219c7af724b24718051407ce11f726b2bfac4b Mon Sep 17 00:00:00 2001 From: Alessandro Bertulli Date: Wed, 5 Nov 2025 22:23:03 +0100 Subject: [PATCH 2/2] Use 
 syntax

---
 README.md | 24 ++++++++++++------------
 1 file changed, 12 insertions(+), 12 deletions(-)

diff --git a/README.md b/README.md
index 1c792be..5aae4fb 100644
--- a/README.md
+++ b/README.md
@@ -45,21 +45,21 @@ This CMake module exports both a C and a C++ API. Both are accessed by including
 call after including the module.
 
 | Description | C API | C++ API[^1] | Output | Git command |
-| ----------- | ----- | ---------- | ------ | ----------- |
-| Check if repo is correctly configured | `bool git_IsPopulated()` | `bool git::IsPopulated()` | `true`/`false` | (Set to `0` if git commands signal an error) |
-| Check if the worktree is dirty (there are uncommited changes)[^2] | `bool git_AnyUncommittedChanges()` | `bool git::AnyUncommittedChanges()` | `true`/`false` | `git status --porcelain -unormal` |
-| Get the author's name | 
const char* git_AuthorName()
 | `const StringOrView& git::AuthorName()` | `"Andrew Hardin"` | `git show -s "--format=%an"` |
-| Get the author's email | const char* git_AuthorEmail() | `const StringOrView& git::AuthorEmail()` | `"andrew.hardin@github.com"` | `git show -s "--format=%ae"` |
-| Get the commit full SHA1 ID | 
const char* git_CommitSHA1()
 | `const StringOrView& git::CommitSHA1()` | `"815da8c5a326f10931c0ce5944c62da11bbe784e"` | `git show -s "--format=%H"` |
-| Get the commit date | 
const char* git_CommitDate()
 | `const StringOrView& git::CommitDate()` | `"2025-11-05 17:01:07 +0100"` | `git show -s "--format=%ci"` |
-| Get the commit subject | `const char* git_CommitSubject()` | `const StringOrView& git::CommitSubject()` | `"An example commit subject"` | `git show -s "--format=%s"` |
-| Get the commit full body | `const char* git_CommitBody()` | `const StringOrView& git::CommitBody()` | `"An example commit body\nthat can span multiple lines"`[^3] | `git show -s "--format=%b"` |
-| Get the commit describe string | `const char* git_Describe()` | `const StringOrView& git::Describe()` | `"v1.0.2-5g815da8c"` | `git describe --always` |
-| Get the current branch | `const char* git_Branch()` | `const StringOrView& git::Branch()` | `"main"` | `git symbolic-ref --short -q` |
+| ----------- | ----- | ----------- | ------ | ----------- |
+| Check if repo is correctly configured | 
bool git_IsPopulated()
 | 
bool git::IsPopulated()
 | `true`/`false` | (Set to `0` if git commands signal an error) |
+| Check if the worktree is dirty (there are uncommited changes)[^2] | 
bool git_AnyUncommittedChanges()
 | 
bool git::AnyUncommittedChanges()
 | `true`/`false` | 
git status --porcelain -unormal
 |
+| Get the author's name | 
const char* git_AuthorName()
 | 
const StringOrView& git::AuthorName()
 | `"Andrew Hardin"` | 
git show -s "--format=%an"
 |
+| Get the author's email | 
const char* git_AuthorEmail()
 | 
const StringOrView& git::AuthorEmail()
 | `"name.surname@github.com"` | 
git show -s "--format=%ae"
 |
+| Get the commit full SHA1 ID | 
const char* git_CommitSHA1()
 | 
const StringOrView& git::CommitSHA1()
 | `"815da8c5a326f10931c0ce5944c62da11bbe784e"` | 
git show -s "--format=%H"
 |
+| Get the commit date | 
const char* git_CommitDate()
 | 
const StringOrView& git::CommitDate()
 | `"2025-11-05 17:01:07 +0100"` | 
git show -s "--format=%ci"
 |
+| Get the commit subject | 
const char* git_CommitSubject()
 | 
const StringOrView& git::CommitSubject()
 | `"An example commit subject"` | 
git show -s "--format=%s"
 |
+| Get the commit full body | 
const char* git_CommitBody()
 | 
const StringOrView& git::CommitBody()
 | `"An example commit body\nthat can span multiple lines"`[^3] | 
git show -s "--format=%b"
 |
+| Get the commit describe string | 
const char* git_Describe()
 | 
const StringOrView& git::Describe()
 | `"v1.0.2-5g815da8c"` | 
git describe --always
 |
+| Get the current branch | 
const char* git_Branch()
 | 
const StringOrView& git::Branch()
 | `"main"` | 
git symbolic-ref --short -q
 |
 
 [^1]: The `StringOrView` type is an alias to `std::string`. By setting the configuration variable `GIT_VERSION_USE_STRING_VIEW` to true, it becomes an alias to `std::string_view`.
 [^2]: By default, it considers untracked files as a dirty worktree. By setting the configuration variable `GIT_IGNORE_UNTRACKED` to true, it ignores them and only considers tracked modified files.
-[^3]: The returned string has whitespace automatically escaped (it will contain printable sequences `"\n"` and `"\r"`)
+[^3]: The returned string has the same whitespace as the original body (it will contain newlines)
 
 ## Q: What if I want to track `$special_git_field`?
 Fork the project and modify [git_watcher.cmake](git_watcher.cmake)