Skip to content

Update-MarkdownCommandHelp fails on rerun when the .bak from the previous run exists #863

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.

Activity

Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Metadata

Metadata

Assignees

No one assigned

    Labels

    No labels
    No labels

    Type

    No type

    Projects

    No projects

      Milestone

      No milestone

      Relationships

      None yet

      Development

      No branches or pull requests

      Issue actions