GitVersion supports C# format strings in configuration, allowing you to apply standard .NET formatting and custom transformations to version properties. This enhancement provides more flexibility and control over how version information is displayed and used throughout your build process.
Custom Version Output
Set custom-version-format to add a CustomVersion value to GitVersion's
output without changing the meaning of any existing version variable. It uses
the same version and environment variable formatting described below and
is empty unless a format is configured. Define it under output to use one
format for every branch, or override it within output.branches when different
deployment modes require different formats.
For example, a PEP 440-compatible pre-release version can omit SemVer's dash and separator:
output:
custom-version-format: '{Major}.{Minor}.{Patch}{PreReleaseLabelName:l}{PreReleaseNumber}'
# 0.6.3-beta.10 becomes CustomVersion 0.6.3beta10
For example, a branch-specific format can override the global default:
output:
branches:
feature:
custom-version-format: '{Major}.{Minor}.{Patch}{PreReleaseLabelName:l}{PreReleaseNumber}'
custom-version-format: '{SemVer}'
A fixed-width numeric format can provide an increasing integer version for platforms such as Android:
output:
custom-version-format: '{Major:00}{Minor:00}{Patch:000}'
# 0.0.123 becomes 0000123; 0.1.0 becomes 0001000
Choose widths that are large enough for each version component and keep the result within the target platform's integer limit. If the CI system owns the monotonically increasing build number, it can be exposed directly instead:
output:
custom-version-format: '{env:ANDROID_VERSION_CODE}'
Source variables
Use CommitCountSourceDistance when formatting the count, and SemVerSourceSemVer or SemVerSourceIncrement when describing the selected semantic baseline:
output:
assembly-informational-format: '{SemVerSourceSemVer}-{SemVerSourceIncrement}+{CommitCountSourceDistance:000}'
# Example: 5.0.0-None+002 for an external 5.0.0 baseline and two counted commits.
SemVerSourceSha can be absent for configuration or branch-name sources; it is not a substitute for Sha (HEAD) or CommitCountSourceSha (the counting anchor). Existing VersionSource* format names remain available for compatibility.
Overview
The custom formatter functionality introduces several new formatters that can be used in GitVersion configuration files and templates:
- FormattableFormatter: Supports standard .NET format strings for numeric values, dates, and implements
IFormattable - NumericFormatter: Handles numeric formatting with culture-aware output
- DateTimeFormatter: Provides date and time formatting with standard and custom format specifiers
- String Case Formatters: Provides text case transformations with custom format specifiers
Standard .NET Format Strings
Numeric Formatting
You can now use standard .NET numeric format strings with version components:
# GitVersion.yml
output:
assembly-informational-format: "{Major}.{Minor}.{Patch:F2}-{PreReleaseLabelName}"
Supported Numeric Formats:
Forf(Fixed-point):{Patch:F2}→"1.23"Norn(Number):{BuildMetadata:N0}→"1,234"Corc(Currency):{Major:C}→"¤1.00"Porp(Percent):{VersionSourceDistance:P}→"12,345.60 %"Dord(Decimal):{Major:D4}→"0001"Borb(Binary):{Minor:B4}→"0101"Xorx(Hexadecimal):{Patch:X}→"FF"
Date and Time Formatting
When working with date-related properties like CommitDate:
output:
assembly-informational-format: "Build-{SemVer}-{CommitDate:yyyy-MM-dd}"
Common Date Format Specifiers:
yyyy-MM-dd→"2024-03-15"HH:mm:ss→"14:30:22"MMM dd, yyyy→"Mar 15, 2024"yyyy-MM-dd'T'HH:mm:ss'Z'→"2024-03-15T14:30:22Z"
Custom String Case Formatters
GitVersion introduces custom format specifiers for string case transformations that can be used in templates:
Available Case Formats
| Format | Description | Example Input | Example Output |
|---|---|---|---|
u |
Uppercase - Converts entire string to uppercase | feature-branch |
FEATURE-BRANCH |
l |
Lowercase - Converts entire string to lowercase | Feature-Branch |
feature-branch |
t |
Title Case - Capitalizes first letter of each word | feature-branch |
Feature-Branch |
s |
Sentence Case - Capitalizes only the first letter | feature-branch |
Feature-branch |
c |
PascalCase - Removes separators and capitalizes each word | feature-branch |
FeatureBranch |
Usage Examples
# GitVersion.yml configuration
calculation:
branches:
feature:
label: "{BranchName:c}" # Converts to PascalCase
output:
assembly-informational-format: "{Major}.{Minor}.{Patch}-{PreReleaseLabelName:l}.{VersionSourceDistance:0000}"
Template Usage:
# Using format strings in templates
output:
assembly-informational-format: "{Major}.{Minor}.{Patch}-{VersionSourceDistance:0000}"
# Alternative:
# assembly-informational-format: "{SemVer}-{BranchName:l}"
Examples
Based on actual test cases from the implementation:
Zero-Padded Numeric Formatting
# Zero-padded commit count
output:
assembly-informational-format: "{Major}.{Minor}.{Patch}-{VersionSourceDistance:0000}"
# Result: "1.2.3-0042"
String Case Transformations
calculation:
branches:
feature:
label: "{BranchName:c}" # PascalCase: "feature-branch" → "FeatureBranch"
hotfix:
label: "hotfix-{BranchName:l}" # Lowercase: "HOTFIX-BRANCH" → "hotfix-branch"
Date and Time Formatting
output:
assembly-informational-format: "{SemVer}-build-{CommitDate:yyyy-MM-dd}"
# Result: "1.2.3-build-2021-01-01"
Numeric Formatting
output:
# Currency format (uses InvariantCulture)
assembly-informational-format: "Cost-{Major:C}" # Result: "Cost-¤1.00"
# Alternative: percentage format
# assembly-informational-format: "Progress-{Minor:P}" # Result: "Progress-200.00 %"
# Alternative: thousands separator
# assembly-informational-format: "Build-{VersionSourceDistance:N0}" # Result: "Build-1,234"
Configuration Integration
The format strings are used in GitVersion configuration files through various formatting properties:
Assembly Version Formatting
# GitVersion.yml
output:
assembly-file-versioning-format: "{MajorMinorPatch}.{VersionSourceDistance}"
assembly-informational-format: "{Major}.{Minor}.{Patch}-{VersionSourceDistance:0000}"
assembly-versioning-format: "{Major}.{Minor}.{Patch}.{env:BUILD_NUMBER}"
Environment Variable Integration
# Using environment variables with fallbacks
output:
assembly-informational-format: "{Major}.{Minor}.{Patch}-{env:RELEASE_STAGE ?? 'dev'}"
# Alternative:
# assembly-informational-format: "{SemVer}+{env:BUILD_ID ?? 'local'}"
Real-World Integration Examples
Based on the actual test implementation:
calculation:
# Branch-specific formatting
branches:
feature:
label: "{BranchName:c}" # PascalCase conversion
hotfix:
label: "hotfix.{VersionSourceDistance:00}"
output:
# Example from VariableProviderTests.cs
assembly-informational-format: "{Major}.{Minor}.{Patch}-{VersionSourceDistance:0000}"
# Result: "1.2.3-0042" when VersionSourceDistance = 42
Invariant Culture Formatting
The formatting system uses CultureInfo.InvariantCulture by default through the chained TryFormat overload implementation. This provides:
- Consistent results across all environments and systems
- Predictable numeric formatting with period (.) as decimal separator and comma (,) as thousands separator
- Standard date formatting using English month names and formats
- No localization variations regardless of system locale
// All environments produce the same output:
// {VersionSourceDistance:N0} → "1,234"
// {CommitDate:MMM dd, yyyy} → "Mar 15, 2024"
// {Major:C} → "¤1.00" (generic currency symbol)
This ensures that version strings generated by GitVersion are consistent across different build environments, developer machines, and CI/CD systems.