Summary
Update-MarkdownCommandHelp fails on every run after the first, because it renames the original to
<file>.md.bak without overwriting, and the backup from the previous run is still there.
The error is non-terminating and per file, so an automated build keeps going, reports success, and
ships documentation that was never updated.
Steps to reproduce
Microsoft.PowerShell.PlatyPS 1.0.3, PowerShell 7.6.5, Windows.
Import-Module Microsoft.PowerShell.PlatyPS -RequiredVersion 1.0.3
$md = '.\docs\DemoMod\Get-DemoThing.md'
foreach ($run in 1..2) {
try { Update-MarkdownCommandHelp -Path $md -ErrorAction Stop | Out-Null; "run $run : OK" }
catch { "run $run : THREW :: $($_.Exception.Message)" }
}
Actual
run 1 : OK (.bak present: True)
run 2 : THREW :: Cannot create a file when that file already exists.
The document is not updated on the second run.
Expected
Either overwrite the previous backup, or version it, or fail with a message that names the backup
collision — currently the text gives no indication that a stale .bak is the cause, or which file
could not be created.
Analysis
The backup is taken with fi.MoveTo($"{path}.bak"). FileInfo.MoveTo(string) does not overwrite,
so it throws IOException once <file>.md.bak exists from an earlier run.
Why this matters more than it looks
-NoBackup avoids it, and in practice every serious build script passes it — I checked a sample and
found it in PSBicep, jborean93/PowerShell-Ansible.Debugger, ArmaanMcleod/PowerShellBuildTools,
chris-peterson/pwsh-gitlab, logicmonitor/lm-powershell-module, krymtkts/pocof and others.
But the reason it is effectively mandatory in automation is documented nowhere. The parameter
reference describes -NoBackup only as suppressing backup creation:
By default, the cmdlet creates a backup of the original Markdown file before updating it. Use this
parameter to suppress the creation of the backup file.
and the conceptual walkthrough actively encourages keeping backups, suggesting you diff against them
and delete them when finished — good advice for a human at a prompt, and a trap for a pipeline that
runs twice.
Combined with the error being non-terminating, the realistic outcome is a build that silently stops
updating its help. Worth either a documentation note that -NoBackup is the right default for
automation, or overwriting the stale backup so a rerun is idempotent.
Summary
Update-MarkdownCommandHelpfails on every run after the first, because it renames the original to<file>.md.bakwithout overwriting, and the backup from the previous run is still there.The error is non-terminating and per file, so an automated build keeps going, reports success, and
ships documentation that was never updated.
Steps to reproduce
Microsoft.PowerShell.PlatyPS1.0.3, PowerShell 7.6.5, Windows.Actual
The document is not updated on the second run.
Expected
Either overwrite the previous backup, or version it, or fail with a message that names the backup
collision — currently the text gives no indication that a stale
.bakis the cause, or which filecould not be created.
Analysis
The backup is taken with
fi.MoveTo($"{path}.bak").FileInfo.MoveTo(string)does not overwrite,so it throws
IOExceptiononce<file>.md.bakexists from an earlier run.Why this matters more than it looks
-NoBackupavoids it, and in practice every serious build script passes it — I checked a sample andfound it in PSBicep, jborean93/PowerShell-Ansible.Debugger, ArmaanMcleod/PowerShellBuildTools,
chris-peterson/pwsh-gitlab, logicmonitor/lm-powershell-module, krymtkts/pocof and others.
But the reason it is effectively mandatory in automation is documented nowhere. The parameter
reference describes
-NoBackuponly as suppressing backup creation:and the conceptual walkthrough actively encourages keeping backups, suggesting you diff against them
and delete them when finished — good advice for a human at a prompt, and a trap for a pipeline that
runs twice.
Combined with the error being non-terminating, the realistic outcome is a build that silently stops
updating its help. Worth either a documentation note that
-NoBackupis the right default forautomation, or overwriting the stale backup so a rerun is idempotent.