githead

Summary

The githead macro returns the SHA-1 hash of the current Git HEAD commit. It searches for a .git directory starting from the project base directory and walking up the file hierarchy, then resolves symbolic references to find the actual commit hash.

Syntax

${githead}

Parameters

None - this macro takes no parameters.

Behavior

• Searches for a .git directory starting from the project base, going up the directory tree
• Handles both regular Git repositories and Git worktrees
• Reads the .git/HEAD file to find the current commit
• Resolves symbolic references (e.g., ref: refs/heads/main) to actual commit SHAs
• Handles packed references (when Git has optimized/compressed references)
• Returns the commit SHA in uppercase hexadecimal format
• Returns empty string if no Git repository is found

Examples

Include Git commit in manifest:

Bundle-SCM-Revision: ${githead}
# Result: Bundle-SCM-Revision: 4A3B2C1D0E9F8A7B6C5D4E3F2A1B0C9D8E7F6A5B

Create version with Git hash:

Implementation-Version: ${version}-${githead}

Document build source:

Build-From: commit ${githead}

Conditional on Git availability:

git.revision=${if;${githead};${githead};not-in-git-repo}

Use Cases

• Tracking exact source code version in built artifacts
• Creating reproducible builds with commit information
• Debugging - knowing exactly which commit produced an artifact
• Audit trails for compliance and security
• Continuous integration - linking builds to source commits
• Version identification beyond semantic versioning

Notes

• Returns empty string if not in a Git repository
• Works with Git worktrees (separate working directories)
• Handles both direct SHA references and symbolic references
• Handles Git’s packed-refs optimization
• The returned SHA is in uppercase
• The search walks up the directory tree to find the Git repository
• Useful for embedding in bundle manifests for traceability

See test cases in MacroTestsForDocsExamples.java