Installation

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).