PowerShell / PowerShell/platyPS

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

Open
#863 0 comments 0 reactions 0 assignees View on GitHub

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

Open the contributing guide

First steps

  1. Read the whole issue, then the project's contributing guide.
  2. Comment on the issue to say you are picking it up — it saves two people doing the same work.
  3. Fork the repository and make your change on a branch.
  4. 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

Get new issues in your inbox

A short digest of beginner-friendly GitHub issues.