Skip to content

CLI.md

Latest commit

 

History

History
188 lines (145 loc) · 8.29 KB

CLI.md

File metadata and controls

188 lines (145 loc) · 8.29 KB
Raw

Command-line reference

Basic forms

EncodingChecker.exe -BasePath <directory> -Target <encoding> [options]
EncodingChecker.exe -Apply <plan.json> [options]

The GUI is usually simplest for one-time work. The command line is useful for repeatable work, CI, and reviewed batch conversions.

For a small job you are reviewing and converting in one session, direct conversion is easiest. For an important batch, automation, or review that happens later, use -Plan followed by -Apply: it binds approval to the exact source files and refuses the entire plan if any scheduled file has changed.

File selection

Option Meaning
-BasePath <directory> Folder to scan. Required except with -Apply.
-Include <patterns> Comma-separated wildcard patterns; may be repeated.
-Exclude <patterns> Comma-separated wildcard patterns; may be repeated.

An explicitly supplied -Include or -Exclude must contain at least one non-empty pattern. Values such as "", ",,,", or whitespace are rejected.

A pattern without / or \ matches file names at any depth. A pattern with a separator matches the path relative to -BasePath. / and \ are equivalent. * and ? are supported wildcards.

EC always excludes files it can recognise as its own by name: .bak backups, .ecmeta.json recovery records, and .unicodechecker.tmp temporaries. It also excludes the plan, journal, and report files written by the current command.

It does not exclude plans, journals, or reports left by earlier runs. You choose those file names, so EC cannot tell them from any other file, and a later conversion of the same folder will rewrite them like anything else. Keep exported plans, journals, and reports outside the folder you scan.

Common metadata and build folders such as .git, bin, obj, and node_modules are skipped, and no pattern reaches into them. Hidden, system, and reparse-point files are left alone, and hidden, system, and reparse-point folders are not entered.

EC reports what each exclusion skipped, so a clean result cannot stand in for complete coverage. For files it reports counts, limited to files your patterns actually selected — so -Include "*.bak" reports that they were skipped instead of returning nothing at all. For skipped folders it reports the folders, not their contents, because it does not walk them to find out.

A folder EC tried to read and could not — a permission denial, or one removed mid-scan — is reported the same way, counted separately from the folders it skipped on purpose. These counts do not change the exit code. A run that could not read part of the tree still exits 0, so a script that must not pass over unexamined content has to read the counts on stderr rather than the exit code alone.

Conversion

Option Meaning
-Target <encoding> Target encoding, for example utf-8 or utf-8-bom. Required for conversion.
-From <encoding> Explicit original encoding for every selected file. Use when you know a legacy source encoding.
-Backup Save the replaced original as <file>.bak. The name is fixed, so converting the same file again replaces that backup.
-WhatIf Show a one-time preview without writing files.
-Plan <path> Write a reviewable conversion plan; do not modify files.
-Apply <path> Execute a saved plan. Its scope and conversion settings are fixed.

EC converts ASCII, Unicode with a BOM, and text whose encoding it can prove from its bytes automatically. Legacy text and BOM-less Unicode whose encoding cannot be proven safely need -From. Choosing a source encoding replaces detection only; strict source decoding, strict target encoding, output verification, backup checks, and atomic installation still apply.

For BOM-less UTF-16, EC converts automatically only when the bytes prove the byte order. If both UTF-16LE and UTF-16BE strictly decode the complete file, EC refuses the automatic conversion. Choose -From utf-16le or -From utf-16be if you know the original order.

BOM-less UTF-32 is never converted automatically, and is reported with reason code UnprovableBomlessUtf32. The bytes cannot establish the codec: UTF-16 text with one character per line also decodes as valid UTF-32. Add a byte-order mark, or pass -From utf-32 or -From utf-32BE.

-Apply uses the decisions and hashes stored in the plan; it does not detect the files again. Only -Journal, -Quiet, and -MaxParallelism may accompany it. -WhatIf, -Target, -From, -Backup, and file-selection options are rejected with -Apply.

-Plan, -Apply, -Journal, and -Report must use different paths. During -Apply, the journal path must not name any source file in the saved plan. -Plan, -Journal, and -Report also cannot use EC's reserved .bak, .ecmeta.json, or .unicodechecker.tmp suffixes, so command output cannot replace a backup or recovery artifact.

Read-only modes

Option Meaning
-DetectOnly Report detected encodings; do not modify files.
-Validate <charset1,...> Strictly validate complete files against an allowed encoding list; do not modify files.
-FailOnChanges Return exit code 2 when files need conversion or fail validation. Useful in CI.

-DetectOnly cannot be combined with -Validate, -Target, -From, -WhatIf, -Backup, -Plan, -Apply, or -Journal. -Validate cannot be combined with conversion options.

Output and performance

Option Meaning
-Report <path> Also write the CSV report as UTF-8 with a BOM for Excel.
-Journal <path> Write a JSON record of the conversion decision and final result for every file. Convert mode only.
-Quiet Suppress per-file CSV and normal summaries. Errors and coverage warnings still go to stderr.
-Verbose Include error details and a result breakdown.
-MaxParallelism <N> Maximum simultaneous files. Default: the smaller of CPU count and 8.

-Quiet and -Verbose cannot be combined.

After cancellation, a requested journal is still saved with Interrupted: true (journal schema 6). GUI and saved-plan runs record known files not reached as NotAttempted. A direct scan records only the files it reached; its journal is not a complete list of the folder. Earlier journals lack this interruption flag.

A requested CSV report is also saved for the files reached. Its Result column uses NotAttempted for unprocessed GUI rows, rather than claiming conversion. Encoding names the source used or attempted; for refused or unprocessed rows, it retains the scan result. It is not proof of the original encoding.

An interrupted preflight does not write a new plan. Any existing plan is left unchanged, and stderr explains this. Ctrl+C returns 4 unless a processing or output-writing error requires 3.

Examples

Preview files without writing anything:

EncodingChecker.exe -BasePath "C:\Files" -Include "*.cs,*.txt" `
  -Exclude "*.g.cs,*.designer.cs" -Target utf-8 -WhatIf

Prepare and later apply an approved batch:

EncodingChecker.exe -BasePath "C:\Files" -Target utf-8 -Backup -Plan plan.json
EncodingChecker.exe -Apply plan.json -Journal conversion.json

Convert known Windows-1252 text while preserving originals:

EncodingChecker.exe -BasePath "C:\Files" -Include "*.txt" `
  -From windows-1252 -Target utf-8 -Backup -Journal conversion.json

Validate a folder in CI:

EncodingChecker.exe -BasePath "C:\Files" -Validate "utf-8,utf-8-bom" `
  -Report validation.csv -FailOnChanges -Quiet

Version and exit codes

EncodingChecker.exe --version

Prints the version and exits. It takes no other arguments and does not need -BasePath.

Code Meaning
0 Completed.
1 Invalid command.
2 -FailOnChanges found files requiring conversion or failing validation.
3 Processing, plan, or report failure.
4 Cancelled with Ctrl+C.
5 One or more conversions were safely refused and left unchanged.

When more than one applies, processing failure (3) wins over cancellation (4), which wins over safe refusal (5), which wins over -FailOnChanges (2). Both cancellable paths - scans (conversion, detection, validation, and preflight) and -Apply - use this precedence. A file failure discovered before Ctrl+C is reported consistently across these modes.