Getting started

GitVersion reads your Git history and configuration to produce version variables. It does not create a release or tag for you.

Working with a coding agent? Use AI-agent onboarding to choose a v7 installation and verify configuration against your repository's history, with v6 as an optional path.

1. Prepare your environment

For the v7 .NET tool, use the .NET 10 SDK. See installation options for supported platforms and alternatives.

Use a repository with the history, tags, and branches needed by your workflow. In CI, start with a full checkout rather than a shallow clone. Read repository requirements.

These examples use v7 arguments. If your installed tool is v6, consult Upgrading.

2. Install GitVersion

dotnet tool install --global GitVersion.Tool --version "7.*"
dotnet-gitversion --version

This command requires a published stable v7 package. Before that release, build v7 from source; an unversioned tool install selects stable v6 and cannot run the v7 examples below.

git clone https://github.com/GitTools/GitVersion.git
dotnet publish GitVersion/src/GitVersion.App/GitVersion.App.csproj --configuration Release --output GitVersion/artifacts/local-cli
dotnet GitVersion/artifacts/local-cli/gitversion.dll --version

For a source build, replace dotnet-gitversion in the remaining examples with dotnet /absolute/path/to/GitVersion/artifacts/local-cli/gitversion.dll. Run it from the repository you want to version, or pass --target-path /path/to/repository.

Use --version <package-version> on the install command to select a specific published version. A local tool manifest can keep the team and CI on the same version.

3. Calculate a version

Open a terminal in an existing Git repository and run:

dotnet-gitversion

The default output is JSON. Your result depends on tags, branch history, configuration, and the tool version. To print just the semantic version:

dotnet-gitversion --show-variable SemVer

4. Understand the result

Variable Use
SemVer Semantic version including a pre-release label when applicable.
FullSemVer Semantic version including build metadata.
MajorMinorPatch The three numeric version components.
AssemblySemVer / AssemblySemFileVer .NET assembly version values.
Sha The commit associated with the result.

See the complete variable reference. A commit count or pre-release number is not a count of how many times your CI job has run.

5. Make versioning explicit

Choose a workflow, then configure GitVersion.yml. Inspect the effective configuration with:

dotnet-gitversion --show-config

Next steps