Heuristic:Datahub project Datahub Git Worktree Gradle Fix
| Knowledge Sources | |
|---|---|
| Domains | Build_System, Git |
| Last Updated | 2026-02-09 17:00 GMT |
Overview
When using git worktrees, always exclude the generateGitPropertiesGlobal task to prevent Gradle build failures.
Description
The DataHub Gradle build includes a generateGitPropertiesGlobal task that generates git metadata (commit hash, branch name, etc.) into build artifacts. This task fails when run inside a git worktree because the git directory structure differs from a standard clone. The workaround is simple: append -x generateGitPropertiesGlobal to any Gradle command when working in a worktree.
Usage
Apply this heuristic whenever running Gradle commands inside a git worktree. If you are using a standard git clone, this heuristic does not apply.
The Insight (Rule of Thumb)
- Action: Append
-x generateGitPropertiesGlobalto all Gradle commands in git worktrees. - Example:
./gradlew build -x generateGitPropertiesGlobal - Trade-off: Git properties will not be embedded in build artifacts, but this is acceptable for local development.
Reasoning
Git worktrees use a different directory layout (.git is a file pointing to the main worktree, not a directory). The git-properties Gradle plugin does not handle this layout correctly, causing IllegalStateException or similar errors. Since git properties are primarily used for version identification in deployed artifacts (not development), excluding the task has no impact on functionality.