Magic File Names

A co-worker discovered an amazing thing the other day. He needed to check out our codebase on a Windows machine (for real, not inside WSL) to do something model-y with Matlab. It’s worked before, and it looked like it was going fine until he got this error:

error: invalid path ‘modules/gnss_icd/include/prn.h’
fatal: unable to checkout working tree
warning: Clone succeeded, but checkout failed.
You can inspect what was checked out with ‘git status’
and retry with ‘git restore –source=HEAD :/’

Invalid path, you say? That’s odd. It works fine in our development environment (Linux) and worked a month ago the last time he tried it. It turns out that the file in question, prn.h, was added in that month. But why would adding a file to a source repository make git checkout stop working?

Some light digging turned this up, which includes this bonkers section:

Do not use the following reserved names for the name of a file: CON, PRN, AUX, NUL, COM1, COM2, COM3, COM4, COM5, COM6, COM7, COM8, COM9, COM1, COM2, COM3, LPT1, LPT2, LPT3, LPT4, LPT5, LPT6, LPT7, LPT8, LPT9, LPT1, LPT2, and LPT3. Also avoid these names followed immediately by an extension; for example, NUL.txt and NUL.tar.gz are both equivalent to NUL.

So if you have a file called prn.h, or aux.c, Windows just can’t handle it. Why, in 2025, is this still a thing?

I did some checking, and if I create files with names like those described above on a Linux machine then mount the filesystem on Windows with CIFS (via Samba), the files just don’t show up at all. They exist on the Linux machine, but as far as Windows is concerned, they don’t.

I also tried mounting that same filesystem over NFS. Instead of silently disappearing the files, it mangles their names. Good times.

Anyway, this is the dumbest thing I’ve heard about in a pretty long time so I figured I’d share.

Edit: When I added this file to the Mercurial repository I use to track these posts, Mercurial spat out this helpful warning:

warning: filename contains ‘prn’, which is reserved on Windows: prn.rst

One more thing to put on my pile of reasons why Git is user-hostile, I guess.

Previous: Immigration