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 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 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:
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.
---
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)