Skip to content

Add summary documentation for the available API #56

New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

Sign up for GitHub

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Open
wants to merge 2 commits into
base: master
Choose a base branch
from
Open

Add summary documentation for the available API #56

Changes from all commits
Commits
Show all changes
2 commits
Select commit Hold shift + click to select a range
ef05c84
Add API documentation
Nov 5, 2025
91219c7
Use <pre></pre> syntax
Nov 5, 2025
File filter

Filter by extension

Filter by extension
Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
23 changes: 22 additions & 1 deletion README.md
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -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
Expand All @@ -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 | <pre>bool git_IsPopulated()</pre> | <pre>bool git::IsPopulated()</pre> | `true`/`false` | (Set to `0` if git commands signal an error) |
| Check if the worktree is dirty (there are uncommited changes)[^2] | <pre>bool git_AnyUncommittedChanges()</pre> | <pre>bool git::AnyUncommittedChanges()</pre> | `true`/`false` | <pre>git status --porcelain -unormal</pre> |
| Get the author's name | <pre>const char* git_AuthorName()</pre> | <pre>const StringOrView& git::AuthorName()</pre> | `"Andrew Hardin"` | <pre>git show -s "--format=%an"</pre> |
| Get the author's email | <pre>const char* git_AuthorEmail()</pre> | <pre>const StringOrView& git::AuthorEmail()</pre> | `"name.surname@github.com"` | <pre>git show -s "--format=%ae"</pre> |
| Get the commit full SHA1 ID | <pre>const char* git_CommitSHA1()</pre> | <pre>const StringOrView& git::CommitSHA1()</pre> | `"815da8c5a326f10931c0ce5944c62da11bbe784e"` | <pre>git show -s "--format=%H"</pre> |
| Get the commit date | <pre>const char* git_CommitDate()</pre> | <pre>const StringOrView& git::CommitDate()</pre> | `"2025-11-05 17:01:07 +0100"` | <pre>git show -s "--format=%ci"</pre> |
| Get the commit subject | <pre>const char* git_CommitSubject()</pre> | <pre>const StringOrView& git::CommitSubject()</pre> | `"An example commit subject"` | <pre>git show -s "--format=%s"</pre> |
| Get the commit full body | <pre>const char* git_CommitBody()</pre> | <pre>const StringOrView& git::CommitBody()</pre> | `"An example commit body\nthat can span multiple lines"`[^3] | <pre>git show -s "--format=%b"</pre> |
| Get the commit describe string | <pre>const char* git_Describe()</pre> | <pre>const StringOrView& git::Describe()</pre> | `"v1.0.2-5g815da8c"` | <pre>git describe --always</pre> |
| Get the current branch | <pre>const char* git_Branch()</pre> | <pre>const StringOrView& git::Branch()</pre> | `"main"` | <pre>git symbolic-ref --short -q</pre> |

[^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 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)
to track new additional fields (e.g. kernel version or build hostname).
Expand Down