Convert-ProjectConsistency

Namespace PSPublishModule

Inputs

None

Outputs

System.Object

Converts a project to a consistent encoding/line ending policy and reports the results.

Remarks

This cmdlet applies a consistency policy (encoding and/or line endings) across a project tree. It can also export a post-conversion report so you can validate what remains inconsistent. For build-time enforcement, use New-ConfigurationFileConsistency -AutoFix in the module build pipeline.

Examples

Authored help example

Convert a PowerShell project to UTF-8 BOM + CRLF

PS>


Convert-ProjectConsistency -Path 'C:\MyProject' -ProjectType PowerShell -CreateBackups

Ensures PowerShell-friendly encoding and line endings, creating backups before changes.

Convert line endings only for a cross-platform repo

PS>


Convert-ProjectConsistency -Path 'C:\MyProject' -FixLineEndings -RequiredLineEnding LF -ExcludeDirectories 'Build','Docs'

Normalizes line endings to LF and skips non-source folders.

Convert encoding only with per-extension overrides

PS>


Convert-ProjectConsistency -Path 'C:\MyProject' -FixEncoding -RequiredEncoding UTF8BOM -EncodingOverrides @{ '*.xml' = 'UTF8' } -ExportPath 'C:\Reports\consistency.csv'

Uses UTF-8 BOM by default but keeps XML files UTF-8 without BOM, and writes a report.

Common Parameters

This command supports the common parameters: -Debug, -ErrorAction, -ErrorVariable, -InformationAction, -InformationVariable, -OutVariable, -OutBuffer, -PipelineVariable, -Verbose, -WarningAction, and -WarningVariable.

For more information, see about_CommonParameters.

Syntax

Convert-ProjectConsistency [-BackupDirectory <String>] [-CreateBackups] [-CustomExtensions <String[]>] [-EncodingOverrides <IDictionary>] [-EnsureFinalNewline] [-ExcludeDirectories <String[]>] [-ExcludeFiles <String[]>] [-ExportPath <String>] [-FixEncoding] [-FixLineEndings] [-Force] [-LineEndingOverrides <IDictionary>] [-NoRollbackOnMismatch] [-OnlyMissingFinalNewline] [-OnlyMixedLineEndings] -Path <String> [-ProjectType <PowerShell|CSharp|Mixed|All|Custom>] [-RequiredEncoding <ASCII>] [-RequiredLineEnding <CRLF|LF>] [-ShowDetails] [-SourceEncoding <Ascii>] [<CommonParameters>]

Parameter set: All Parameter Sets

Parameters

BackupDirectory String optionalposition: namedpipeline: False: Backup root folder (mirrors the project structure).
CreateBackups SwitchParameter optionalposition: namedpipeline: False: Create backup files before modifying content.
CustomExtensions String[] optionalposition: namedpipeline: False: Custom file extensions to include when ProjectType is Custom (e.g., *.ps1, *.cs).
EncodingOverrides IDictionary optionalposition: namedpipeline: False: Per-path encoding overrides (hashtable of pattern => encoding).
EnsureFinalNewline SwitchParameter optionalposition: namedpipeline: False: Ensure a final newline exists after line ending conversion.
ExcludeDirectories String[] optionalposition: namedpipeline: False: Directory names to exclude from conversion (e.g., .git, bin, obj).
ExcludeFiles String[] optionalposition: namedpipeline: False: File patterns to exclude from conversion.
ExportPath String optionalposition: namedpipeline: False: Export the detailed report to a CSV file at the specified path.
FixEncoding SwitchParameter optionalposition: namedpipeline: False: Convert encoding inconsistencies.
FixLineEndings SwitchParameter optionalposition: namedpipeline: False: Convert line ending inconsistencies.
Force SwitchParameter optionalposition: namedpipeline: False: Force conversion even when the file already matches the target.
LineEndingOverrides IDictionary optionalposition: namedpipeline: False: Per-path line ending overrides (hashtable of pattern => line ending).
NoRollbackOnMismatch SwitchParameter optionalposition: namedpipeline: False: Do not rollback from backup if verification mismatch occurs during encoding conversion.
OnlyMissingFinalNewline SwitchParameter optionalposition: namedpipeline: False: Only fix files missing the final newline.
OnlyMixedLineEndings SwitchParameter optionalposition: namedpipeline: False: Only convert files that have mixed line endings.
Path String requiredposition: namedpipeline: False: Path to the project directory to convert.
ProjectType String optionalposition: namedpipeline: Falsevalues: 5: Type of project to analyze. Determines which file extensions are included.; Possible values: PowerShell, CSharp, Mixed, All, Custom
RequiredEncoding FileConsistencyEncoding optionalposition: namedpipeline: Falsevalues: 7: Target encoding to enforce when fixing encoding consistency.; Possible values: ASCII, UTF8, UTF8BOM, Unicode, BigEndianUnicode, UTF7, UTF32
RequiredLineEnding FileConsistencyLineEnding optionalposition: namedpipeline: Falsevalues: 2: Target line ending style to enforce when fixing line endings.; Possible values: CRLF, LF
ShowDetails SwitchParameter optionalposition: namedpipeline: False: Include detailed file-by-file analysis in the output.
SourceEncoding TextEncodingKind optionalposition: namedpipeline: Falsevalues: 10: Source encoding filter. When Any, any non-target encoding may be converted.; Possible values: Ascii, BigEndianUnicode, Unicode, UTF7, UTF8, UTF8BOM, UTF32, Default, OEM, Any

Outputs

System.Object