Release Management

PSScriptBuilder includes a built-in release management system for SemVer version bumping, build metadata tracking, Git context capture, and automated file updates via configurable bump patterns.

How It Works

Release management is based on two JSON files in your project:

File	Purpose
psscriptbuilder.releasedata.json	Stores the current version, build metadata, and Git context
psscriptbuilder.bumpconfig.json	Defines which files get updated and how (patterns / tokens)

These files are configured in psscriptbuilder.config.json:

{
    "release": {
        "dataFile":       ".\\build\\Release\\psscriptbuilder.releasedata.json",
        "bumpConfigFile": ".\\build\\Release\\psscriptbuilder.bumpconfig.json"
    }
}

Release Data Structure

The release data file holds the authoritative version and metadata:

{
    "version": {
        "major":         1,
        "minor":         2,
        "patch":         0,
        "prerelease":    null,
        "buildmetadata": null,
        "full":          "1.2.0"
    },
    "build": {
        "number":    42,
        "date":      "2026-03-23",
        "time":      "14:42:26",
        "timestamp": "2026-03-23T14:42:26Z",
        "year":      2026,
        "month":     3,
        "day":       23,
        "hour":      14,
        "minute":    42,
        "second":    26
    },
    "git": {
        "commit":      "2a98ae58cc96e12c78614ec28ed044996ee86d43",
        "commitShort": "2a98ae5",
        "branch":      "main",
        "tag":         "v1.2.0"
    }
}

Create the Release Data File

If no release data file exists yet, create one with default values (0.1.0):

New-PSScriptBuilderReleaseData

Use -Force to overwrite an existing file. Use -WhatIf to preview what would be created.

Bumping the Version

Update-PSScriptBuilderReleaseData is the central cmdlet for all version and metadata updates.

# Bump patch version (0.1.0 → 0.1.1)
Update-PSScriptBuilderReleaseData -Patch

# Bump minor version (0.1.1 → 0.2.0), also update build and Git details
Update-PSScriptBuilderReleaseData -Minor -UpdateBuildDetails -UpdateGitDetails

# Bump major version (0.2.0 → 1.0.0)
Update-PSScriptBuilderReleaseData -Major

# Add a prerelease identifier
Update-PSScriptBuilderReleaseData -Patch -Prerelease "rc.1"

# Remove prerelease (1.0.0-rc.1 → 1.0.0)
Update-PSScriptBuilderReleaseData -ClearPrerelease

# Preview changes without applying them
Update-PSScriptBuilderReleaseData -Minor -UpdateBuildDetails -WhatIf

Version Bump Rules

Switch	Effect
-Major	Increments major, resets minor and patch to 0
-Minor	Increments minor, resets patch to 0
-Patch	Increments patch
-Prerelease "alpha.1"	Sets the prerelease identifier
-ClearPrerelease	Removes the prerelease identifier
-BuildMetadata "build.5"	Sets build metadata (not auto-updated)
-ClearBuildMetadata	Removes build metadata

Only one version bump switch (-Major, -Minor, -Patch) may be used at a time. At least one operation must be specified per call — either a version bump or a metadata/details switch (-UpdateBuildDetails, -UpdateGitDetails, -Prerelease, -ClearPrerelease, -BuildMetadata, -ClearBuildMetadata).

Updating Build and Git Metadata

Switch	Updates
-UpdateBuildDetails	build.date, build.time, build.timestamp, all time components, build.number (+1)
-UpdateGitDetails	git.commit, git.commitShort, git.branch, git.tag (requires git in PATH)

These can be combined with version bumps or used alone:

# Only refresh Git context, no version change
Update-PSScriptBuilderReleaseData -UpdateGitDetails

# Only update build details (re-stamp timestamp, increment build number)
Update-PSScriptBuilderReleaseData -UpdateBuildDetails

Displaying the Result

Pipe the result to Format-PSScriptBuilderReleaseDataResult for a readable summary:

Update-PSScriptBuilderReleaseData -Patch -UpdateBuildDetails | Format-PSScriptBuilderReleaseDataResult

Output:

Category: Version

  Property  : patch
  Old Value : 1
  New Value : 2

  Property  : full
  Old Value : 0.1.1
  New Value : 0.1.2

Category: Build

  Property  : number
  Old Value : 41
  New Value : 42

Reading Release Data

# Hierarchical view (Version / Build / Git)
$data = Get-PSScriptBuilderReleaseData
$data.Version.Full
$data.Build.Timestamp
$data.Git.Branch

# Flat view — all properties prefixed
$flat = Get-PSScriptBuilderReleaseData -Flat
$flat.VersionFull
$flat.BuildTimestamp
$flat.GitBranch

Available Tokens

Tokens are derived from the release data and used in bump file patterns. Use Get-PSScriptBuilderReleaseDataTokens to see all current values:

Get-PSScriptBuilderReleaseDataTokens | Format-Table -AutoSize

Version Tokens

Token	Value
VERSION	major.minor.patch (e.g. 1.2.0)
VERSION_FULL	Full SemVer including prerelease and metadata (e.g. 1.2.0-rc.1+build.5)
VERSION_MAJOR	Major number only
VERSION_MINOR	Minor number only
VERSION_PATCH	Patch number only
VERSION_PRERELEASE	Prerelease identifier or empty
VERSION_BUILDMETADATA	Build metadata or empty

Build Tokens

Token	Value
BUILD_NUMBER	Incrementing build counter
BUILD_DATE	yyyy-MM-dd
BUILD_TIME	HH:mm:ss
BUILD_TIMESTAMP	yyyy-MM-ddTHH:mm:ssZ
BUILD_YEAR, BUILD_MONTH, BUILD_DAY	Individual date components
BUILD_HOUR, BUILD_MINUTE, BUILD_SECOND	Individual time components

Git Tokens

Token	Value
GIT_COMMIT	Full 40-character SHA1 hash
GIT_COMMIT_SHORT	Short hash (7+ characters)
GIT_BRANCH	Current branch name
GIT_TAG	Latest tag, or empty if none

Bump Files — Applying Tokens to Project Files

After updating the release data, use Update-PSScriptBuilderBumpFiles to propagate the version and metadata to all configured project files (manifests, templates, changelogs, etc.):

Update-PSScriptBuilderBumpFiles

View which files would be modified without applying changes:

Update-PSScriptBuilderBumpFiles -WhatIf

Display a detailed change report:

Update-PSScriptBuilderBumpFiles | Format-PSScriptBuilderBumpResult

Bump Configuration File

psscriptbuilder.bumpconfig.json defines which files to update and how. Each entry in bumpFiles targets one file, using either simple token replacement or regex-based pattern matching.

PSScriptBuilder uses its own bump configuration for its releases, making this a real-world example rather than a constructed one:

{
    "bumpFiles": [
        {
            "description": "PSScriptBuilder root module template - Auto token replacement",
            "path": "build\\Templates\\PSScriptBuilder.psm1.template",
            "tokens": ["VERSION", "VERSION_FULL", "BUILD_TIMESTAMP", "GIT_COMMIT_SHORT", "BUILD_DATE", "BUILD_TIME"]
        },
        {
            "description": "PSScriptBuilder root module template - Multi-phase bumping",
            "path": "build\\Templates\\PSScriptBuilder.psm1.template",
            "items": [
                {
                    "pattern": "Version\\s*=\\s*'({REGEX_VERSION_FULL})'",
                    "tokens": ["VERSION_FULL"]
                },
                {
                    "pattern": "BuildTimestamp\\s*=\\s*'({REGEX_BUILD_TIMESTAMP})'",
                    "tokens": ["BUILD_TIMESTAMP"]
                },
                {
                    "pattern": "GitCommit\\s*=\\s*'({REGEX_GIT_COMMIT_SHORT})'",
                    "tokens": ["GIT_COMMIT_SHORT"]
                }
            ]
        },
        {
            "description": "PSScriptBuilder Module Manifest (.psd1) - Multi-phase bumping",
            "path": "build\\Output\\PSScriptBuilder.psd1",
            "items": [
                {
                    "pattern": "{{VERSION}}",
                    "tokens": ["VERSION"]
                },
                {
                    "pattern": "ModuleVersion\\s*=\\s*'({REGEX_VERSION})'",
                    "tokens": ["VERSION"]
                }
            ]
        }
    ]
}

Entry 1 — Module template, simple token mode

The module template contains {{TOKEN}} placeholders. The tokens array lists which tokens to replace; PSScriptBuilder substitutes each with the corresponding release data value.

Entry 2 — Module template, regex mode (multi-phase)

The same template file appears a second time using items with regex patterns. When the same path appears more than once in bumpFiles, all entries are applied sequentially to the same in-memory content. The regex patterns target actual values already in the file:

• Version = '...' — updates the module version string
• BuildTimestamp = '...' — updates the ISO 8601 timestamp
• GitCommit = '...' — updates the short commit hash

Entry 3 — Module manifest, regex mode

Two items target PSScriptBuilder.psd1. The first pattern matches a {{VERSION}} placeholder (for freshly initialized manifests), the second matches the existing ModuleVersion = '...' key-value line. Having both ensures the manifest is updated correctly in either state.

Simple Token Mode (tokens)

Replaces {{TOKEN}} placeholders directly in the file content. Use this when the file already contains placeholder strings:

{
    "path": "src\\MyScript.ps1",
    "tokens": ["VERSION_FULL", "BUILD_TIMESTAMP"]
}

The file would contain:

$version = '{{VERSION_FULL}}'
$buildTime = '{{BUILD_TIMESTAMP}}'

Regex Pattern Mode (items)

Each item defines a pattern (regular expression) and the tokens to replace inside it. Use {REGEX_TOKEN} inside the pattern as a named capture group that gets replaced:

{
    "pattern": "ModuleVersion\\s*=\\s*'({REGEX_VERSION})'",
    "tokens": ["VERSION"]
}

This matches the existing value in the file and replaces only the captured group — everything outside the parentheses is preserved. The file does not need placeholder strings; it works on any existing file format.

Multiple items can target the same file. The same file can also appear multiple times in bumpFiles for multi-phase processing — all entries for one file are applied sequentially to the same in-memory content.

Inspecting the Bump Configuration

# View all configured bump file entries
Get-PSScriptBuilderBumpConfiguration

# List all file paths that will be updated
Get-PSScriptBuilderBumpConfiguration | ForEach-Object { $_.path }

Validation

Always validate before running updates:

# Validate release data file
if (-not (Test-PSScriptBuilderReleaseData)) {
    Write-Error "Release data is invalid — fix it before bumping"
    return
}

# Validate bump configuration
if (-not (Test-PSScriptBuilderBumpConfiguration)) {
    Write-Error "Bump configuration is invalid — fix it before running Update-PSScriptBuilderBumpFiles"
    return
}

Full Release Workflow

A typical release script combining all steps:

using module PSScriptBuilder

Set-PSScriptBuilderProjectRoot -Path '.'

# 1. Validate
if (-not (Test-PSScriptBuilderReleaseData)) { return }
if (-not (Test-PSScriptBuilderBumpConfiguration)) { return }

# 2. Bump version, update build and Git metadata
Update-PSScriptBuilderReleaseData -Patch -UpdateBuildDetails -UpdateGitDetails |
    Format-PSScriptBuilderReleaseDataResult

# 3. Apply tokens to all configured files
Update-PSScriptBuilderBumpFiles | Format-PSScriptBuilderBumpResult

# 4. Build the module
$cc = New-PSScriptBuilderContentCollector |
    Add-PSScriptBuilderCollector -Type Class    -IncludePath '.\src\Classes' |
    Add-PSScriptBuilderCollector -Type Function -IncludePath '.\src\Public'

Invoke-PSScriptBuilderBuild -ContentCollector $cc `
    -TemplatePath '.\build\Templates\MyModule.psm1.template' `
    -OutputPath   '.\build\Output\MyModule.psm1'

See Also

• Cmdlet Reference: Update-PSScriptBuilderReleaseData
• Cmdlet Reference: Update-PSScriptBuilderBumpFiles
• Cmdlet Reference: Get-PSScriptBuilderReleaseDataTokens