GitVersion's command line interface can be installed and consumed in many different ways. Read about the options below.
For an agent-assisted setup, follow AI-agent onboarding to select a pinned v7 distribution, preserve existing installations and test configuration against local history. It also includes an optional v6 path.
.NET Global Tool
GitVersion can be installed as a .NET global tool under the name
GitVersion.Tool by executing the following in a terminal:
dotnet tool install --global GitVersion.Tool
Hint: To install a specific version of GitVersion.Tool, use the --version flag of dotnet tool install
Example: dotnet tool install GitVersion.Tool --global --version 7.0.0
If you want to pin to a specific version of GitVersion, you can find the available
versions of GitVersion.Tool on NuGet.
GitVersion v7 uses RID-specific tool packages targeting .NET 10 and .NET 11. The install command requires the .NET 10 SDK or later; NuGet selects the package for the current platform automatically. GitVersion ships dedicated packages for Windows x64 and ARM64, Linux x64 and ARM64 (including musl), and Intel and Apple Silicon macOS.
The .NET 11 target requires the .NET 11 GA runtime or a compatible servicing release. The .NET 10 target remains available. Standalone self-contained archives continue to use .NET 10; the Docker build matrix covers both .NET 10 and .NET 11 using the published GitTools base images.
To run call
dotnet-gitversion
.NET Local Tool
GitVersion can also be installed as a .NET local tool using a tool manifest. This approach is useful for ensuring that all team members use the same version of GitVersion in a project.
To install GitVersion as a local tool, execute the following in your project's root directory:
dotnet new tool-manifest # if you don't already have a manifest file
dotnet tool install GitVersion.Tool
This creates or updates a .config/dotnet-tools.json file in your repository
that specifies the version of GitVersion to use. You can commit this file to
source control.
Hint: To install a specific version of GitVersion.Tool as a local tool, use the --version flag
Example: dotnet tool install GitVersion.Tool --version 7.0.0
To restore tools specified in the manifest (for example, after cloning the repository):
dotnet tool restore
To run the local tool, you have several options:
dotnet gitversion
Alternatively, you can use dotnet tool exec (or its
shorthand aliases dotnet dnx or just dnx) to explicitly execute the tool:
dotnet tool exec GitVersion.Tool
# or using the shorthand alias
dotnet dnx GitVersion.Tool
# or even shorter
dnx GitVersion.Tool
Note: The dotnet tool exec, dotnet dnx, and dnx commands are useful in scripts or CI/CD
pipelines where you want to be explicit about executing a local tool from the manifest.
When using these commands, you must specify the package name GitVersion.Tool rather than the command name.
Note that local tools use dotnet gitversion (without the hyphen), while the
global tool uses dotnet-gitversion (with a hyphen).
The same SDK and platform requirements as the global tool apply.
Homebrew
To install the gitversion formula with Homebrew,
enter the following into a terminal:
brew install gitversion
Arguments are available with gitversion --help (short alias -h is also supported).
Long-form arguments are recommended in scripts and documentation.
This should work on all operating systems supported by Homebrew (at the time of writing: Linux and macOS).
Chocolatey
Available on Chocolatey as
GitVersion.Portable.
choco install GitVersion.Portable
This should work on all operating systems supported by Chocolatey (at the time of writing: Windows).
Docker
gittools/gitversion allows you to use GitVersion through Docker,
without installing any other dependencies. To use the Docker image, execute
the following:
docker run --rm -v "$(pwd):/repo" gittools/gitversion:latest-ubuntu.26.04 /repo
GitVersion v7 images run as UID/GID 10001:10001, which needs write access to the
mounted repository. On Linux, add --user "$(id -u):$(id -g)" when running from
the non-root checkout owner's shell if the default image user cannot write to
the checkout. The image handles an unwritable home automatically; no HOME or
DOTNET_CLI_HOME flags are needed. See Docker repository permissions.
The important arguments here are:
| Argument | Description |
|---|---|
"$(pwd):/repo" |
Maps the output of pwd (the working directory) to the /repo directory within the Docker container. |
gittools/gitversion:{tag} |
The name and tag of the GitVersion container to use. |
/repo |
The directory within the Docker container GitVersion should use as its working directory. Don't change this. |
Caveat: The --output buildserver option doesn't work universally with
Docker since environment variables defined inside the Docker container will not
be exposed to the host OS.
This should work on all operating systems supported by Docker (at the time of writing: Linux, macOS, Windows).