Note: GitVersion uses POSIX-style --long-name arguments from version 7 and up. Long-form
arguments are recommended for readability in scripts and documentation. Short aliases
(e.g. -l, -o, -b) are also supported. The legacy /switch and -switch
syntax is available during v7.0 when GITVERSION_ARGUMENT_PARSER_VERSION=v6 is set.
The default is v7. Unset the retired GITVERSION_USE_V6_ARGUMENT_PARSER
variable; it now produces a replacement diagnostic. The legacy parser is
removed in v7.1 and the selector in v8.
See Migration v6 to v7 for upgrade guidance and the full argument mapping.
Help
Optional POSIX CLI usage telemetry can be disabled with --telemetry-opt-out,
DO_NOT_TRACK=1, or GITVERSION_TELEMETRY_OPTOUT=true. See Telemetry for collection scope,
sampling, privacy and the fixed campaign window.
The first eligible direct run with a positive direct sampling probability, or the first selected automated
run, links to the Telemetry policy and collected data on stderr.
Below is the output from gitversion --help as a best effort to provide
documentation for which arguments GitVersion supports and their meaning.
Use convention to derive a SemVer product version from a GitFlow or GitHub based
repository.
GitVersion [path]
path The directory containing .git. If not defined current
directory is used. (Must be first argument)
--version Displays the version of GitVersion
--diagnose, -d Runs GitVersion with additional diagnostic information;
also needs the '--log-file' argument to specify a logfile
or stdout (requires git.exe to be installed)
--help, -h Shows Help
--cli-schema Writes the complete OpenCLI 0.1 command schema as JSON and exits.
--target-path Same as 'path', but not positional
--output, -o Determines the output to the console. Can be either 'json',
'file', 'buildserver' or 'dotenv', will default to 'json'.
--output-file Path to output file. It is used in combination with
--output 'file'.
--show-variable, -v
Used in conjunction with --output json, will output just a
particular variable.
E.g. --output json --show-variable SemVer
- will output `1.2.3+beta.4`
--format, -f Used in conjunction with --output json, will output a format
containing version variables.
Supports C# format strings - see [Format Strings](/docs/reference/custom-formatting) for details.
E.g. --output json --format {SemVer} - will output `1.2.3+beta.4`
--output json --format {Major}.{Minor} - will output `1.2`
--log-file, -l Path to logfile; specify 'console' to emit to stderr.
--config, -c Path to config file (defaults to GitVersion.yml, GitVersion.yaml, .GitVersion.yml or .GitVersion.yaml)
--show-config Outputs the effective GitVersion config (defaults + custom
from GitVersion.yml, GitVersion.yaml, .GitVersion.yml or .GitVersion.yaml) in yaml format.
With v7 configuration, runtime overrides are also included.
--override-config
Overrides GitVersion config values inline (key=value pairs,
e.g. --override-config workflow=GitHubFlow/v1).
Repeat --override-config for multiple overrides.
--no-cache Bypasses the cache, result will not be written to the cache.
--no-normalize Disables normalize step on a build server.
--allow-shallow Allows GitVersion to run on a shallow clone.
This is not recommended, but can be used if you are sure
that the shallow clone contains all the information needed
to calculate the version.
--verbosity Specifies the amount of information to be displayed.
(Quiet, Minimal, Normal, Verbose, Diagnostic)
Default is Normal
# AssemblyInfo updating
--update-assembly-info
Will recursively search for all 'AssemblyInfo.cs' files in
the git repo and update them
--update-project-files
Will recursively search for all project files
(.csproj/.vbproj/.fsproj/.sqlproj) files in the git repo and update
them
Note: This is only compatible with the newer Sdk projects
--ensure-assembly-info
If the assembly info file specified with
--update-assembly-info is not
found, it will be created with these attributes:
AssemblyFileVersion, AssemblyVersion and
AssemblyInformationalVersion.
Supports writing version info for: C#, F#, VB
# Create or update Wix version file
--update-wix-version-file
All the GitVersion variables are written to
'GitVersion_WixVersion.wxi'. The variables can then be
referenced in other WiX project files for versioning.
# Remote repository args
--url Url to remote git repository.
--branch, -b Target branch to version (local or with --url). Takes
precedence over GIT_BRANCH/Git_Branch, which only supply
branch context at HEAD.
--username, -u Username in case authentication is required.
--password, -p Password in case authentication is required.
--commit The commit id to check. If not specified, the latest
available commit on the specified branch will be used.
--dynamic-repo-location
By default dynamic repositories will be cloned to %tmp%.
Use this switch to override
--no-fetch Disables 'git fetch' during version calculation. Might cause
GitVersion to not calculate your version as expected.
Validate configuration
Validate a candidate with the established v7 POSIX CLI before inspecting effective settings:
gitversion config validate --config GitVersion.yml
gitversion config validate --target-path ./candidate-directory
gitversion config validate --config "candidate configs/équipe.yml" --format json
gitversion config validate --config GitVersion.yml --override-config calculation.tag-prefix='[vV]?'
An explicit file works outside Git and offline. Without --config, discovery checks
the selected directory and, inside Git, the repository root. Files in both directories
are ambiguous. Within a directory, existing priority is GitVersion.yml,
GitVersion.yaml, .GitVersion.yml, then .GitVersion.yaml.
Case variants at the same priority use ordinal path order.
Missing/unreadable files fail; validation never substitutes defaults for a missing
file. An existing empty document resolves workflow defaults.
Validation shares normal execution's deserializer, layout mapper, workflow defaults, override precedence and builder. Both paths reject unknown/misplaced public keys, wrong types or enum names, invalid workflows, invalid configured regexes and references to unconfigured branch definitions. Regex checks include ignore paths, branches and tags, tag/branch version patterns, bump messages and merge-message formats. Diagnostics omit configuration values and report the first error.
next-version must parse with the selected semantic-version-format (Strict
requires a complete version such as 2.0.0; Loose permits partial versions).
Commit cutoff dates are checked without inspecting commits.
The command never calculates a version, constructs a Git backend, fetches, normalizes
refs, writes caches, migrates configuration or emits build-server/file-update
outputs. It accepts --config, --override-config, --target-path and its local
--format json. A root positional directory must precede config validate.
Calculation, remote, file-update and logging options are rejected, including when
placed before the command. Help and --cli-schema remain informational operations.
By default, the summary and diagnostics go to stderr and stdout is empty. Exit 0 means the resolved configuration is valid; command-executed invocation, configuration and file-read errors return 1. Warnings do not fail validation; there is no strict-warning flag in this initial command.
--format json writes exactly one JSON document to stdout, followed by a newline.
The human summary and diagnostics remain on stderr:
{
"schemaVersion": 1,
"valid": true,
"configurationVersion": "v7",
"file": "/workspace/GitVersion.yml",
"diagnostics": []
}
file is the selected absolute path, or null when selection failed.
Each diagnostic contains code, severity (error or warning), path (public
property path, or empty for a document/invocation error), message, line and
column. Locations are one-based when provided by YAML parsing, otherwise null.
Codes are stable within schema version 1; human messages may change:
| Code | Meaning |
|---|---|
GVCONFIG_FILE |
Missing or unreadable configuration file |
GVCONFIG_DISCOVERY |
Ambiguous discovery |
GVCONFIG_INVOCATION |
Incompatible command option or output format |
GVCONFIG_OVERRIDE |
Invalid override syntax or unsupported override path |
GVCONFIG_YAML |
YAML syntax or deserialization error |
GVCONFIG_LAYOUT |
Wrong layout or section ownership |
GVCONFIG_PROPERTY |
Unknown key, invalid type or enum |
GVCONFIG_WORKFLOW |
Unknown workflow |
GVCONFIG_REGEX |
Invalid regular expression |
GVCONFIG_BRANCH |
Missing branch regex or unresolved branch reference |
GVCONFIG_VALUE |
Invalid semantic value or invocation path |
GVCONFIG_V6_COMPATIBILITY |
Non-failing temporary v6 compatibility warning |
Parser failures before command execution (unknown options, missing option arguments, extra positional arguments) retain ordinary stderr/exit 1 behavior without JSON. Feature-selector errors also occur before command execution.
Configuration layout selection remains separate from parser selection. Explicit
GITVERSION_CONFIGURATION_VERSION=v6 accepts flat files during v7.0 and emits the
existing warning; legacy loading is removed in v7.1. Invalid v7 documents never
fall back to v6. Use config migrate to convert a legacy file. This command is
unavailable with the legacy parser and published v6 tools.
Validation does not establish that versions match your release policy. Inspect effective configuration next and verify calculations on representative existing history. A preview workflow, a different branching model, or the absence of matching branches in history is not itself a validation error.
Query a configuration property
Use gitversion config get <property-path> to read one scalar from the effective
v7 configuration. It uses the same configuration discovery, workflow defaults,
file settings and runtime overrides as --show-config. It requires a Git
repository, but does not calculate a version or update build-agent outputs or
version files. As with full display, conflicting configuration files in the
working directory and repository root require an explicit --config path.
# Default tag prefix: "[vV]?"
gitversion config get calculation.tag-prefix
# Runtime override: false
gitversion config get output.update-build-number --override-config output.update-build-number=false
# Unknown property: diagnostic on stderr, empty stdout, exit status 1
gitversion config get calculation.no-such-property
Paths are case-sensitive, dot-separated public configuration names, such as
calculation.tag-prefix, output.assembly-versioning-scheme, root workflow,
or calculation.prevent-increment.of-merged-branch. CLR names and flat v6 paths
are not accepted. Empty segments, escaping, wildcards and array indexing are
not supported. Maps (including branch entries and merge-message-formats),
collections and whole objects cannot be queried. A missing map key therefore
produces an unsupported-map diagnostic, not a null value.
Successful stdout contains exactly one JSON scalar followed by a newline:
| Value | Output |
|---|---|
| String or enum name | JSON string, e.g. "MajorMinorPatch" |
| Empty string | "" |
| Boolean | true or false |
| Number | Culture-independent JSON number, e.g. 60000 |
| Known property whose resolved value is null | null |
Strings retain their type: a string containing null is emitted as "null".
Quotes, newlines and other special characters are JSON-escaped. Version-format
strings are returned literally; placeholders are not evaluated. A known null
property remains queryable even when full YAML display omits it. The query
returns the final resolved value and does not distinguish a default null from
an explicitly configured null.
Success, including null, returns status 0. Unknown properties, invalid paths,
unsupported values and configuration errors return status 1 with a diagnostic
on stderr and no value on stdout. Logging and warnings also use stderr or the
selected log file. These are document settings, not branch-specific inherited
runtime behavior or calculated version variables; --show-variable continues
to select calculated version variables.
Supported options are --config/-c, repeated --override-config key=value,
--target-path, --log-file/-l and --verbosity. A positional repository path
must precede config get. Version-output, calculation and file-update options
cannot be combined with this command. Use gitversion config get --help for help.
The command requires the default modern argument parser and default or explicit
GITVERSION_CONFIGURATION_VERSION=v7. Selecting v6 configuration produces a
v7-required error before configuration loading, even when the modern parser is
selected; GitVersion does not switch versions implicitly. Existing v6 full
configuration display retains its behavior. With v7 configuration,
--show-config now includes runtime overrides, matching the query result.
CLI schema
gitversion --cli-schema exports the command tree in the OpenCLI format.
It is available with the default v7 argument parser and does not require a Git repository.
Configuration migration
The default POSIX-style argument parser exposes a config migrate subcommand for converting a v6
configuration document to the v7 calculation/output layout:
gitversion config migrate
gitversion config migrate --config GitVersion.yml --output GitVersion.v7.yml
gitversion config migrate --config GitVersion.yml --in-place
It discovers a supported configuration filename when --config is omitted and
writes YAML to stdout unless --output or --in-place is selected. --output
will not replace an existing file without --force; it cannot be combined with
--in-place. Replacing a file warns that comments are not preserved. The
command does not require a Git repository and is unavailable when
GITVERSION_ARGUMENT_PARSER_VERSION=v6 selects the legacy parser. Migration
remains available after v6 runtime support is removed in v7.1.
Override config
--override-config key=value will override appropriate key from 'GitVersion.yml', 'GitVersion.yaml', '.GitVersion.yml' or '.GitVersion.yaml'.
With the v7 default configuration layout, use a version-aware nested key. For
example, calculation.tag-prefix=custom,
calculation.branches.main.increment=Patch, and
output.branches.main.pre-release-weight=55000. Flat v6 keys are rejected in
v7 mode with their nested replacement. Set
GITVERSION_CONFIGURATION_VERSION=v6 only while validating a legacy file in
v7.0.
When that temporary v6 fallback is selected, use the legacy branch override
path, for example --override-config branches.main.increment=Patch.
To specify multiple options add multiple --override-config key=value entries:
--override-config key1=value1 --override-config key2=value2.
To have space characters as a part of value, value has to be enclosed with double quotes - key="My value".
Double quote character inside of the double quoted value has to be escaped with a backslash '\' - key="My \"escaped-quotes\"".
The following override paths are supported in v7. For the temporary v6
fallback, omit the calculation. or output. prefix. The shared workflow
key stays at the root in both versions:
output.assembly-file-versioning-formatoutput.assembly-file-versioning-schemeoutput.assembly-informational-formatoutput.assembly-versioning-formatoutput.assembly-versioning-schemeoutput.commit-date-formatcalculation.commit-message-incrementingoutput.custom-version-formatcalculation.labelcalculation.incrementcalculation.major-version-bump-messagecalculation.minor-version-bump-messagecalculation.modecalculation.next-versioncalculation.no-bump-messagecalculation.patch-version-bump-messagecalculation.tag-prefixoutput.tag-pre-release-weightoutput.update-build-numbercalculation.version-bump-reset-messageworkflow
Read more about Configuration.
Using override-config on the command line will not change the contents of the config file GitVersion.yml, GitVersion.yaml, .GitVersion.yml or .GitVersion.yaml.
Example: How to override configuration option 'tag-prefix' to use prefix 'custom'
GitVersion.exe --output json --override-config calculation.tag-prefix=custom
Example: How to override configuration option 'assembly-versioning-format'
GitVersion.exe --output json --override-config output.assembly-versioning-format="{Major}.{Minor}.{Patch}.{env:BUILD_NUMBER ?? 0}"
Uses the environment variable BUILD_NUMBER, or falls back to zero for the assembly revision number.
Example: How to override configuration option 'assembly-versioning-scheme'
GitVersion.exe --output json --override-config output.assembly-versioning-scheme=MajorMinor
Will use only major and minor version numbers for assembly version. Assembly build and revision numbers will be 0 (e.g. 1.2.0.0)
Example: How to override multiple configuration options
GitVersion.exe --output json --override-config calculation.tag-prefix=custom --override-config output.assembly-versioning-scheme=MajorMinor
Example: How to override configuration option 'update-build-number'
GitVersion.exe --output json --override-config output.update-build-number=true
Example: How to override configuration option 'next-version'
GitVersion.exe --output json --override-config calculation.next-version=6