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

说明与用途

使用 RepoPort 和 GitHub Actions 检查 Git 文件名的 Windows 兼容性，防止在合并前出现错误。

问题

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.

结果

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

工作流

• 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.

证据

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

来源

[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.

来源

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

来源

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

来源