When Git Filenames Break Windows Checkouts — How to Catch Them in CI?

Description and use

Check Git filenames for Windows portability using RepoPort and GitHub Actions to block problematic commits before merge.

Problem

Git repositories can checkout successfully on Linux but fail on Windows due to filenames that the Windows filesystem cannot handle, such as case‑conflicting names or reserved device names.

Outcome

The CI workflow detects and blocks commits containing filenames that would break on Windows, ensuring cross‑platform compatibility before code integration.

Workflow

• Create a disposable repo on Linux and add the problematic files to the Git index.
• Run RepoPort locally with python -m repoport check . to detect case collisions and Windows‑reserved names.
• Rename the conflicting files using git mv to unique names and commit the changes.
• Add a GitHub Actions workflow that checks the Git index with RepoPort on every push and pull request.
• Configure the workflow to fail if RepoPort exits with code 1, preventing merges with problematic filenames.

Evidence

Git can track all three paths. Whether another system can check them out is a different question.

Source

[case-collision] 'assets/Logo.svg', 'assets/logo.svg': These paths collide after NFC normalization and Unicode case folding; choose names that remain distinct without case sensitivity.

Source

[windows-reserved-name] 'docs/NUL.txt': Windows reserves this device name, including with extensions; rename this file or directory.

Source

The workflow checks the index populated by actions/checkout for the revision under test.

Source