Backup-Folder.ps1

#Requires -Version 5.1
<#
.SYNOPSIS
    Copies a folder into <DestinationRoot>\yyyy_MM_dd.

.DESCRIPTION
    PowerShell port of src/vbs/BackupFolder.vbs. Emits the DirectoryInfo of the
    folder it created, so it composes with Remove-Item, Compress-Archive and the
    rest of the pipeline.

.PARAMETER Path
    Folder to back up.

.PARAMETER DestinationRoot
    Folder that receives the dated snapshot folder. Created when missing.

.PARAMETER Retain
    Keep only the newest N dated folders under DestinationRoot. 0 keeps all.

.EXAMPLE
    .\Backup-Folder.ps1 -Path "$env:USERPROFILE\Downloads" -DestinationRoot D:\backup -Retain 30
#>
[CmdletBinding(SupportsShouldProcess)]
param(
    [Parameter(Mandatory)]
    [ValidateScript({ Test-Path -LiteralPath $_ -PathType Container })]
    [string]$Path,

    [Parameter(Mandatory)]
    [ValidateNotNullOrEmpty()]
    [string]$DestinationRoot,

    [ValidateRange(0, 3650)]
    [int]$Retain = 0
)

Set-StrictMode -Version Latest
$ErrorActionPreference = 'Stop'

if (-not (Test-Path -LiteralPath $DestinationRoot)) {
    New-Item -Path $DestinationRoot -ItemType Directory -Force | Out-Null
}

$stamp = Get-Date -Format 'yyyy_MM_dd'
$target = Join-Path -Path $DestinationRoot -ChildPath $stamp

if ($PSCmdlet.ShouldProcess($target, "copy $Path into")) {
    if (-not (Test-Path -LiteralPath $target)) {
        New-Item -Path $target -ItemType Directory | Out-Null
    }
    Copy-Item -LiteralPath $Path -Destination $target -Recurse -Force
}

if ($Retain -gt 0) {
    Get-ChildItem -LiteralPath $DestinationRoot -Directory |
        Where-Object { $_.Name -match '^\d{4}_\d{2}_\d{2}$' } |
        Sort-Object Name -Descending |
        Select-Object -Skip $Retain |
        ForEach-Object {
            if ($PSCmdlet.ShouldProcess($_.FullName, 'remove expired backup')) {
                Remove-Item -LiteralPath $_.FullName -Recurse -Force
            }
        }
}

Get-Item -LiteralPath $target