Distinguish variables read by GitVersion from version variables exported to your build.
Repository and execution inputs
GIT_BRANCH supplies branch context for the checked-out commit, including detached
HEAD and pull-request merge checkouts. Git_Branch is an alias on every platform.
The precedence is explicit CLI --branch or API RepositoryInfo.TargetBranch, then
nonblank GIT_BRANCH, then nonblank Git_Branch, then the provider's branch ref,
then HEAD. On case-sensitive platforms, GIT_BRANCH wins an alias conflict.
Empty and whitespace-only values are absent.
An environment override behaves like a branch at the checked-out commit: its name
selects branch configuration and appears in version outputs, while its history is
the history reachable from that commit. No physical branch is required. If a branch
with that name already points elsewhere, its ref and the checkout remain unchanged.
Cache entries include this context. The override also works with --no-normalize;
when normalization is enabled it can fetch history, but does not rewrite branches
or attach HEAD for the override.
For a contextual pull-request branch whose merge message identifies the target,
a successful preparation fetch makes the matching remote-tracking target take
precedence over a stale local target. Local refs remain unchanged. When preparation
does not fetch (including --no-fetch, --no-normalize, local builds, or a provider
that disables fetching), target selection retains its normal local preference.
Use a valid Git branch name such as feature/work. refs/heads/feature/work is
accepted as feature/work; refs/remotes/origin/feature/work also supplies
feature/work context. A short name such as origin/feature/work is literal.
Whitespace-only values such as GIT_BRANCH=" " are ignored without an error;
resolution continues with Git_Branch, then the provider's branch ref, then HEAD.
Nonblank names are not trimmed, so GIT_BRANCH=" feature/work " is invalid.
Invalid names, tag refs and pull-request refs are
rejected. To label a PR merge checkout, supply the intended branch name, for example
GIT_BRANCH=feature/work. Provider tag detection remains separate; do not use this
variable to select a tag or commit.
Explicit branch and commit options retain their target-selection semantics;
--branch can select another branch's history, and an explicit --commit keeps
the existing history/time-based selection behavior. For a dynamic repository, an
environment override uses the freshly cloned repository's default HEAD, or the
reused clone's HEAD. Use --branch to select a remote target instead.
GitVersion reads the configuration file from the working/project directory as usual; an environment branch override does not check out another configuration file. Provider-specific detection is described in the CI guides.
The v6 to v7 migration guide documents the independent selectors GITVERSION_ARGUMENT_PARSER_VERSION, GITVERSION_CONFIGURATION_VERSION, and GITVERSION_GIT_BACKEND. Their v7.0 defaults are v7, v7, and managed; temporary fallbacks are v6, v6, and libgit2. Values are trimmed and case-insensitive; blank values use the defaults and unknown values fail with accepted-value guidance. The retired GITVERSION_USE_V6_ARGUMENT_PARSER variable must be unset. Legacy implementations are removed in v7.1 and selectors in v8.
Output variables
With a supported build-server integration, version variables are made available using the provider's mechanisms. A common environment-variable spelling is GitVersion_SemVer. Use the exact naming and job/step scope described for your provider.
A child process cannot generally set environment variables in its parent shell. For shell scripts, use JSON or dotenv output and explicitly pass the result to later commands.
For .NET builds, see the MSBuild integration. For every available value and its meaning, see version variables.