--- name: windows-filename-guidance os: win32 description: "Use for Windows filename rules and failures involving reserved DOS device names such as NUL, invalid or trailing characters, inaccessible cross-platform names, long paths, or files that Windows cannot inspect, rename, or delete normally." --- # Windows Filename Guidance ## Diagnose - Separate filesystem rules, Win32 namespace/normalization, and application API handling. An unusual name alone does not prove corruption or permission failure. - Obtain the exact absolute path, entry type, filesystem, and error. Enumerate the parent; never use `Test-Path NUL` or `if exist NUL` as file-existence evidence. - Classify reserved names, trailing characters, path length, open handles, ACLs, or independently evidenced corruption. - Consult current [Microsoft naming rules](https://learn.microsoft.com/en-us/windows/win32/fileio/naming-a-file) through Devdocs rather than retaining character/device-name tables here. - Prefer the namespace or tool that created the entry when it can address it safely. ## Namespace and shell boundaries - Exact absolute extended paths: local `\\?\C:\absolute\path`; UNC `\\?\UNC\server\share\path`. The prefix does not bypass filesystem rules, permissions, locks, or corruption. Never combine it with relative paths. - Git Bash/MSYS2 can rewrite arguments to native executables, including embedded shell text. Use the documented `MSYS2_ARG_CONV_EXCL` boundary; do not assume `MSYS_NO_PATHCONV` covers every executable. - Bash double quotes consume one leading backslash from `\\`. Preserve extended-path spelling with single quotes at that boundary; native cmd.exe quoting is not portable to Bash. - Consult [MSYS2 path conversion](https://www.msys2.org/docs/filesystem-paths/) for exact syntax before constructing a cross-shell command. ## Removal and verification - Show the exact target and obtain explicit confirmation before deletion. Reject wildcards, relative paths, drive/share roots, and ambiguous targets. - Enumerate nonempty directories and obtain separate recursive-delete confirmation. - Choose an operation matching file/directory type and the exact namespace. Preserve spelling, extension, spaces, and periods. Explain forced read-only removal before using it. - If using an 8.3 alias, verify its mapping to the exact target first. - Enumerate the parent afterward; success requires the literal entry to be absent. Missing parent entry means stop, not further deletion attempts. - Git status is not direct filesystem verification. If it alone remains stale, bypass its filesystem monitor/untracked cache once: ```text git -c core.fsmonitor=false -c core.untrackedCache=false status --short ``` - If that resolves the stale report and Git uses the built-in monitor, restart that monitor rather than deleting again. - Identify lock owners and permission boundaries before remediation. Do not elevate, change ownership, or repair a filesystem without independently supported need and authorization. ## Sources - [Microsoft undeletable NTFS entries](https://learn.microsoft.com/en-us/troubleshoot/windows-server/backup-and-storage/cannot-delete-file-folder-on-ntfs-file-system) - [Bash quoting](https://www.gnu.org/software/bash/manual/html_node/Double-Quotes.html) - [Git filesystem monitor](https://git-scm.com/docs/git-fsmonitor--daemon)