You signed in with another tab or window. Reload to refresh your session.You signed out in another tab or window. Reload to refresh your session.You switched accounts on another tab or window. Reload to refresh your session.Dismiss alert
{{ message }}
Repository navigation
Update-MarkdownCommandHelp fails on rerun when the .bak from the previous run exists #863
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.
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.
Activity