CHANGELOG.md

@@ -6,6 +6,8 @@ The format follows [Keep a Changelog](https://keepachangelog.com/en/1.1.0/) loos
 
 ## Unreleased
 
+- `build.ps1` gains a `-CommitArtifacts` switch that, after a successful build, stages and commits only the build outputs (`Module/PSInfisicalAPI/bin/**`, `Module/PSInfisicalAPI/PSInfisicalAPI.psd1`, and the auto-inserted `CHANGELOG.md` build stamp) with a message that references the source commit whose hash is now embedded in `BuildCommitHash`. The switch is mutually exclusive with the older broader `-CommitOnSuccess` (which still uses `git add -A`). README extended with a "Committing source and build artifacts in lockstep" section describing the recommended two-commit workflow.
+
 ## 2026.06.04.1917
 
 - Build produced from commit a34db831d8bf.

README.md

@@ -230,6 +230,16 @@ After adding (or removing) a cmdlet:
 4. Add a `## Unreleased` entry to `CHANGELOG.md` describing the change (mark removals of public cmdlets or parameters as **BREAKING**).
 5. Run `./build.ps1 -RunTests`. The script enforces the cmdlet list, runs the xUnit suite, and verifies that every exported cmdlet has a valid synopsis, description, and at least one non-empty example.
 
+### Committing source and build artifacts in lockstep
+
+The embedded `BuildCommitHash` in `Module/PSInfisicalAPI/PSInfisicalAPI.psd1` and the bundled DLL is captured from `git rev-parse HEAD` at build time. To keep the embedded hash truthful, commit source and build artifacts as two ordered commits:
+
+1. Stage and commit your source changes first. Suppose this produces commit `S`.
+2. Run `./build.ps1 -RunTests -CommitArtifacts`. The build picks up `S` as `HEAD`, embeds it as `BuildCommitHash`, then stages and commits **only** the build outputs (`Module/PSInfisicalAPI/bin/**`, `Module/PSInfisicalAPI/PSInfisicalAPI.psd1`, and the `CHANGELOG.md` build-stamp insertion). The commit message references `S` so the binary commit always traces back to its source.
+3. `git push`.
+
+`-CommitArtifacts` only touches the three artifact paths above; any other dirty files in your working tree are left alone. Use the older `-CommitOnSuccess` switch only when you intentionally want a single commit covering everything (`git add -A` + `git commit -m "Build <version>"`); the two switches are mutually exclusive.
+
 ## Continuous integration
 
 `.gitea/workflows/publish-psgallery.yml` publishes the module to the PowerShell Gallery whenever a pull request is merged into `main`. The workflow expects a repository secret named `PSGALLERY_API_KEY` containing a valid Gallery API key.

build.ps1

@@ -15,9 +15,15 @@ param(
 
     [switch]$CommitOnSuccess,
 
+    [switch]$CommitArtifacts,
+
     [switch]$Force
 )
 
+if ($CommitOnSuccess.IsPresent -and $CommitArtifacts.IsPresent) {
+    throw "-CommitOnSuccess and -CommitArtifacts are mutually exclusive."
+}
+
 $ErrorActionPreference = 'Stop'
 Set-StrictMode -Version Latest
 
@@ -390,4 +396,30 @@ if ($CommitOnSuccess.IsPresent) {
     if ($LASTEXITCODE -ne 0) { throw "git commit failed." }
 }
 
+if ($CommitArtifacts.IsPresent) {
+    Write-Step "Committing build artifacts (embedded BuildCommitHash=$commitHash)"
+    $artifactPaths = @(
+        [System.IO.Path]::Combine('Module', 'PSInfisicalAPI', 'bin'),
+        [System.IO.Path]::Combine('Module', 'PSInfisicalAPI', 'PSInfisicalAPI.psd1'),
+        'CHANGELOG.md'
+    )
+
+    foreach ($artifactPath in $artifactPaths) {
+        & git -C $RepositoryRoot.FullName add -- $artifactPath
+        if ($LASTEXITCODE -ne 0) { throw "git add '$artifactPath' failed." }
+    }
+
+    $stagedOutput = & git -C $RepositoryRoot.FullName diff --cached --name-only
+    if ($LASTEXITCODE -ne 0) { throw "git diff --cached failed." }
+    $stagedFiles = @($stagedOutput | Where-Object { -not [string]::IsNullOrWhiteSpace($_) })
+    if ($stagedFiles.Count -eq 0) {
+        Write-Step "No build artifact changes to commit."
+    } else {
+        $subject = "Build artifacts for $commitHash"
+        $body    = "Auto-generated by build.ps1 -CommitArtifacts. Build $buildVersion. Module DLL and manifest embed BuildCommitHash=$commitHash, matching the source commit they were produced from."
+        & git -C $RepositoryRoot.FullName commit -m $subject -m $body
+        if ($LASTEXITCODE -ne 0) { throw "git commit failed." }
+    }
+}
+
 Write-Step "Build complete."