PowerShell / PowerShell/platyPS
Update-MarkdownCommandHelp fails on rerun when the .bak from the previous run exists
Nobody has claimed this yet.
- Dominant language
- C#
- Stars
- 871
- Forks
- 166
- Avg merge
- 21h 17m
- Merged PRs (30d)
- 1
Description
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.
Contributor guide
First steps
- Read the whole issue, then the project's contributing guide.
- Comment on the issue to say you are picking it up — it saves two people doing the same work.
- Fork the repository and make your change on a branch.
- Open a pull request that references the issue number.
Research direction
Start by locating the Update-MarkdownCommandHelp entry point and the FileInfo.MoveTo call described in the issue. Reproduce the two-run case with the provided PowerShell commands, then inspect nearby tests if present. Done means rerunning the command no longer fails on an existing .bak, or the resulting behavior and documentation clearly address the collision.
Written by the indexing model from the issue text.
Assessment
- Tech stack
- csharp, powershell
- Domain
- cli, documentation
- Issue type
- Bug
- Difficulty
- 3/5
- Estimated time
- 1-2 days
- Activity status
- Active
- Clarity
- Mostly clear
- Newbie friendliness
- 62/100