Format Strings

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:

  • F or f (Fixed-point): {Patch:F2} → "1.23"
  • N or n (Number): {BuildMetadata:N0} → "1,234"
  • C or c (Currency): {Major:C} → "¤1.00"
  • P or p (Percent): {VersionSourceDistance:P} → "12,345.60 %"
  • D or d (Decimal): {Major:D4} → "0001"
  • B or b (Binary): {Minor:B4} → "0101"
  • X or x (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.