What does filepath.IsLocal report about a path name, and which names does it reject?

## The question IsLocal answers `func filepath.IsLocal(path string) bool` reports whether `path`, using lexical analysis only, has all of these properties: it is within the subtree rooted at the directory in which it is evaluated; it is not absolute; it is not empty; and, on Windows, it is not a reserved name such as `NUL`. The useful part is the guarantee that follows. If `IsLocal(name)` is true then `filepath.Join(base, name)` produces a path contained within `base`, and `filepath.Clean(name)` produces an unrooted path with no `..` elements. That is the exact property you want from an untrusted name before it becomes part of a real path, and it is the property `Join` and `Clean` on their own do not give you. ## What it rejects, concretely - **The empty string.** `IsLocal("")` is false. An empty element is not a name, and letting it through means a caller who sent nothing addresses the base directory itself. - **Absolute paths.** `/etc/passwd` is false. Note that `Join` would nest such an element rather than honour it, but a name arriving absolute is a name you did not expect, and IsLocal says so. - **Escaping `..`.** `../x` and `a/../../x` are false. The test is on the cleaned form: a name whose `..` elements consume more than the name itself built up escapes. - **Windows reserved and volume-qualified names.** On Windows, device names like `NUL`, `CON` and `COM1` are false, as are names carrying a volume. This is one of the few places where the same Go code makes a different decision per GOOS, and it is deliberate — those names would not stay inside the directory on that platform. What it accepts: ordinary relative names, and interior `..` that nets out inside, such as `a/../b`, which cleans to `b`. ## The slash-separated cousin Names that arrive over a wire are slash-separated regardless of the operating system you run on: archive entry names, URL path segments, keys from a manifest. `filepath.Localize(path string) (string, error)` is built for those. It takes a slash-separated path, checks the same locality property, and returns the equivalent path in the OS's own syntax — or an error if the name is not local. Using it means you do a single conversion-and-check instead of remembering to call `IsLocal` and then `FromSlash` in the right order. ## What IsLocal is not It is a **lexical** predicate. It opens nothing, stats nothing, and follows nothing. A name that IsLocal accepts can still reach outside the directory when the filesystem is asked to resolve it, because a component along the way may be a symlink pointing elsewhere. IsLocal cannot know that, and it does not claim to. So the role it plays in real code is a *filter*, not a *boundary*. Reject early and loudly with `IsLocal` — you get a clean error message naming the offending entry, and you never construct a nonsense path at all — and then perform the actual open through a directory handle (`os.OpenRoot`, whose `Root.Open`, `Root.Create` and `Root.OpenFile` fail on anything that leaves the root, symlinks included). The two are complementary: the predicate gives you a good diagnostic, the handle gives you the guarantee. ## Where it shows up Anywhere a name crosses a trust boundary and then becomes part of a filesystem path: entries in a submitted archive, upload filenames, a template or plugin name from a request, a key from a job payload. In each case the right shape is the same — validate the *element* you were handed, never the string you built out of it, and let the failure be a rejection of that entry rather than a path that quietly points somewhere else. A final practical note: on the accept path, keep the name you validated and the name you use identical. Re-deriving a name after the check (re-joining, re-cleaning, appending an extension by string surgery) throws away the property the check established.