GitVersion Documentation

GitVersion uses a two-step process to determine the version number:

1. Calculate the base version: It identifies the highest version number found across all available version sources.
2. Calculate the next version: It uses the base version and increments it based on your branch configuration and then appends build metadata (the part after the +).

If the current commit is explicitly tagged, GitVersion uses that tag as the version immediately.

GitVersion automates Semantic Versioning (SemVer) by analyzing your git history rather than relying on manual version files or build server configurations.

Key benefits include:

• Deterministic Versioning: Rebuilding tags always produces the same version.
• No Manual Increments: You do not need to rebuild or commit just to increment a version number.
• Single Source of Truth: Eliminates the need to duplicate version information in multiple places (like version.txt or branch names).
• Branch-Aware SemVer: Each branch calculates its own SemVer, and versions flow correctly between branches during merges.
• Unique PR Versions: Pull requests automatically produce unique pre-release version numbers.
• Automated Integration: Handles NuGet SemVer issues, build server integration, and assembly info updates automatically.

GitVersion automates the calculation of the next semantic version based on your Git workflow. The version increment logic varies depending on the branching model used:

• GitFlow: When the main branch is tagged, GitVersion will typically bump the minor version on the develop branch.
• GitHubFlow: GitVersion will typically bump the patch version.

GitVersion provides various versioning formats via Variables. For example, while standard SemVer follows {major}.{minor}.{patch}-{tag}, the FullSemVer variable includes build metadata: {major}.{minor}.{patch}-{tag}+{buildmetadata}.

Starting from version 3.0, GitVersion uses a configuration-driven approach rather than hard-coded branching strategies.

• Default Strategies: GitVersion ships with internal default configurations that support GitHubFlow, GitFlow, and potentially others.
• Develop Branch Behavior: The develop branch is set to ContinuousDeployment mode by default to align with standard GitFlow usage.

GitVersion v3 calculates versions using a three-step process driven by configuration rather than hard-coded branch logic. The steps are:

1. Tag Check: If the current commit is tagged, GitVersion uses that tag and adds build metadata (excluding commit count). This bypasses the subsequent two steps.
2. Strategy Evaluation: A set of versioning strategies are evaluated to determine the base version and associated metadata.
3. Selection: The highest base version identified from the strategies is selected, and the final version is calculated based on that base.

When using GitFlow, builds off the develop branch can be configured to increment on every commit. This is known as continuous deployment mode.

By default, develop builds are assigned an alpha pre-release tag to ensure they are sorted higher than release branches. If you need to consume these packages, it is recommended to publish them to a separate NuGet feed (an alpha channel) to avoid polluting stable feeds.

To use GitVersion in TeamCity via a standard command line step, create a new build step with the following configuration:

• Runner type: Command Line
• Run: Executable with parameters
• Command executable: GitVersion.exe
• Command parameters: --output buildserver --update-assembly-info true

GitVersion will automatically write system parameters into TeamCity, making them available as build parameters (e.g., GitVersion.Major) for subsequent build steps.

To make GitVersion variables available in your environment or to pass them between CI steps (e.g., in GitHub Actions or GitLab CI), redirect the dotenv output to a file. You can then load this file into your environment.

# Write version variables in Dotenv format into a file
gitversion --output dotenv > gitversion.env

GitHub Flow is a simple branching strategy suitable for continuous delivery. It is commonly used by open source projects and follows these principles:

• Mainline development: Performed on the main branch.
• Feature branches: Work is done on separate branches and merged into main via pull requests.
• Limitations: It does not provide a mechanism to manage or maintain old releases and only allows working on a single release at a time.

If using GitHubFlow, you can avoid versioning conflicts by tagging stable versions manually:

1. Set GitVersion to continuous-deployment mode (so main produces -ci.x pre-release builds).
2. Configure CI builds to only create NuGet packages for stable builds.
3. Tag main with a stable version and push the tag.
4. The CI build triggers, and GitVersion respects the tag to produce a stable version.
5. The stable package is pushed to Octopus.
6. The next build will automatically increment and produce pre-release packages for the subsequent version.

To use GitVersion within GitLab CI, you have two primary options:

1. Use the MSBuild Task.
2. Ensure the GitVersion executable is included in your runner's PATH.