windows-compatibility

Cross-platform path handling requires using path.join and path.resolve to construct paths safely across Windows, macOS, and Linux. This prevents platform-specific directory separator bugs and ensures reliable file operations in mixed-OS environments.

Git commit commands fail in PowerShell when inline newlines are passed in commit messages. To prevent cross-platform git workflow failures, use temporary files for commit messages and change directories before executing repository operations instead of using git -C.

Safe filenames from ISO timestamps on Windows require replacing colons with valid characters. Centralizing a safeTimestamp utility ensures generated filenames avoid illegal characters and remain valid across platforms during file creation and path validation.

Case-insensitive path comparisons are necessary for cross-platform development on Windows and macOS where file systems are case-insensitive. Applying platform-aware case handling prevents false negatives during rootDir confinement checks and path validation.

The best way to write reliable cross-platform CI scripts is to normalize filenames, use path.join for directory construction, and apply platform-aware git workflows. These patterns prevent platform-specific bugs in mixed-OS automation and repository tooling.

You should avoid using git -C with Windows paths when executing git workflows in PowerShell or cross-platform automation. Prefer changing directories first and using temporary files for commit messages to prevent command failures and newline issues.