Add Copy-PnPFileMetadata cmdlet and docs

Author: alirobe

documentation/Copy-PnPFileMetadata.md

@@ -0,0 +1,187 @@
+---
+Module Name: PnP.PowerShell
+schema: 2.0.0
+applicable: SharePoint Online
+online version: https://pnp.github.io/powershell/cmdlets/Copy-PnPFileMetadata.html
+external help file: PnP.PowerShell.dll-Help.xml
+title: Copy-PnPFileMetadata
+---
+  
+# Copy-PnPFileMetadata
+
+## SYNOPSIS
+
+Synchronizes metadata between files and folders in SharePoint
+
+## SYNTAX
+
+```powershell
+Copy-PnPFileMetadata [-SourceUrl] <String> [-TargetUrl] <String> [-Fields <String[]>] [-Recursive] [-Force] [-Connection <PnPConnection>] [-SourceConnection <PnPConnection>] [-TargetConnection <PnPConnection>]
+```
+
+## DESCRIPTION
+
+Synchronizes metadata (Created, Modified, Author, Editor) from source files and folders to their corresponding targets without copying the actual content. This cmdlet is particularly useful for restoring lost metadata after migration operations where system fields may have been reset.
+
+When updating items, the cmdlet uses `UpdateOverwriteVersion()` to allow setting system fields while avoiding new user-facing versions.
+
+For folder contents, files are processed one-by-one.
+
+## EXAMPLES
+
+### EXAMPLE 1
+
+```powershell
+Copy-PnPFileMetadata -SourceUrl "Shared Documents/MyProject" -TargetUrl "/sites/target/Shared Documents/MyProject"
+```
+
+Synchronizes metadata for the MyProject folder and all its contents recursively from the source to the target location, preserving original creation dates, modification dates, and author information.
+
+### EXAMPLE 2
+
+```powershell
+Copy-PnPFileMetadata -SourceUrl "Shared Documents/report.docx" -TargetUrl "/sites/archive/Documents/report.docx"
+```
+
+Synchronizes metadata for a single file from the source to the target, restoring the original system fields.
+
+### EXAMPLE 3
+
+```powershell
+Copy-PnPFileMetadata -SourceUrl "Shared Documents/Projects" -TargetUrl "/sites/backup/Documents/Projects" -Fields @("Created", "Modified") -Force
+```
+
+Synchronizes only the Created and Modified dates for the Projects folder and its contents, without prompting for confirmation.
+
+### EXAMPLE 4
+
+```powershell
+Copy-PnPFileMetadata -SourceUrl "Shared Documents/Archives" -TargetUrl "/sites/newsite/Documents/Archives" -Recursive:$false
+```
+
+Synchronizes metadata only for the Archives folder itself, without processing its subfolders and files.
+
+### EXAMPLE 5
+
+```powershell
+$src = Connect-PnPOnline -Url https://contoso.sharepoint.com/sites/archives -ReturnConnection
+$dst = Connect-PnPOnline -Url https://contoso.sharepoint.com/sites/projects -ReturnConnection
+Copy-PnPFileMetadata -SourceUrl "Shared Documents/MyProject" -TargetUrl "Shared Documents/MyProject" -SourceConnection $src -TargetConnection $dst -Verbose
+```
+
+Synchronizes metadata across two different site connections.
+
+## PARAMETERS
+
+### -Force
+
+If provided, no confirmation will be requested and the action will be performed
+
+```yaml
+Type: SwitchParameter
+Parameter Sets: (All)
+
+Required: False
+Position: Named
+Default value: None
+Accept pipeline input: False
+Accept wildcard characters: False
+```
+
+### -Fields
+
+Specifies which metadata fields to synchronize. Default fields are Created, Modified, Author, and Editor.
+
+```yaml
+Type: String[]
+Parameter Sets: (All)
+
+Required: False
+Position: Named
+Default value: @("Created", "Modified", "Author", "Editor")
+Accept pipeline input: False
+Accept wildcard characters: False
+```
+
+### -Recursive
+
+If provided, processes folders recursively including all subfolders and files. This is enabled by default.
+
+```yaml
+Type: SwitchParameter
+Parameter Sets: (All)
+
+Required: False
+Position: Named
+Default value: $true
+Accept pipeline input: False
+Accept wildcard characters: False
+```
+
+
+
+### -SourceUrl
+
+Site or server relative URL specifying the file or folder to copy metadata from. Must include the file name if it is a file or the entire path to the folder if it is a folder.
+
+```yaml
+Type: String
+Parameter Sets: (All)
+Aliases: ServerRelativeUrl
+
+Required: True
+Position: 0
+Default value: None
+Accept pipeline input: True (ByValue)
+Accept wildcard characters: False
+```
+
+### -TargetUrl
+
+Site or server relative URL specifying the file or folder to copy metadata to. Must include the file name if it is a file or the entire path to the folder if it is a folder.
+
+```yaml
+Type: String
+Parameter Sets: (All)
+Aliases: TargetServerRelativeUrl
+
+Required: True
+Position: 1
+Default value: None
+Accept pipeline input: False
+Accept wildcard characters: False
+```
+
+### -SourceConnection
+
+Optional connection to be used for accessing the source file or folder. If not provided, the current connection is used.
+
+```yaml
+Type: PnPConnection
+Parameter Sets: (All)
+
+Required: False
+Position: Named
+Default value: None
+Accept pipeline input: False
+Accept wildcard characters: False
+```
+
+### -TargetConnection
+
+Optional connection to be used for accessing the target file or folder. If not provided, the current connection is used.
+
+```yaml
+Type: PnPConnection
+Parameter Sets: (All)
+
+Required: False
+Position: Named
+Default value: None
+Accept pipeline input: False
+Accept wildcard characters: False
+```
+
+## RELATED LINKS
+
+[Microsoft 365 Patterns and Practices](https://aka.ms/m365pnp)