| Order | 10 |
|---|---|
| Title | Installation |
| Description | How to install the GitVersion Command Line Interface |
GitVersion's command line interface can be installed and consumed in many different ways. Read about the options below.
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:::{.alert .alert-info} Hint: To install an older version of GitVersion.Tool, use the --version flag of dotnet tool install
Example: dotnet tool install GitVersion.Tool --global --version 6.*
:::
If you want to pin to a specific version of GitVersion, you can find the available
versions of GitVersion.Tool on NuGet.
This should work on all operating systems supported by .NET Core.
To run call
dotnet-gitversionGitVersion 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.ToolThis 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.
:::{.alert .alert-info} Hint: To install a specific version of GitVersion.Tool as a local tool, use the --version flag
Example: dotnet tool install GitVersion.Tool --version 6.*
:::
To restore tools specified in the manifest (for example, after cloning the repository):
dotnet tool restoreTo run the local tool, you have several options:
dotnet gitversionAlternatively, 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:::{.alert .alert-info}
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).
This should work on all operating systems supported by .NET Core.
To install the gitversion formula with Homebrew,
enter the following into a terminal:
brew install gitversionSwitches are available with gitversion -h. Even though the documentation
uses a slash / for all switches, you need to use a dash - instead, since /
is interpreted as a root path on POSIX based operating systems.
This should work on all operating systems supported by Homebrew (at the time of writing: Linux and macOS).
Available on Chocolatey as
GitVersion.Portable.
choco install GitVersion.PortableThis should work on all operating systems supported by Chocolatey (at the time of writing: Windows).
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-debian.12 /repoThe 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. |
:::{.alert .alert-warning}
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).