fileflow-pathologize

Safe File Operations: fileflow & pathologize

Two small, composable spf13 libraries that handle the two things naive file code gets wrong: moving files safely (fileflow) and making names safe (pathologize).

When to Activate

• Moving, copying, or renaming files — especially across drives/volumes
• Handling the "destination already exists" case without clobbering data
• Seeing invalid cross-device link / EXDEV from os.Rename
• Building a destination path from a filename, user input, or a regex capture
• Downloaders, extractors, importers, file organizers, upload handlers
• Anywhere you were about to write os.Rename + io.Copy + filepath.Clean by hand

Why These Over the Standard Library

os.Rename fails across filesystems (EXDEV) and silently overwrites the destination. filepath.Clean normalizes .. but does not remove characters that are illegal on other operating systems, and does nothing about reserved names (CON, NUL). And path/filepath validates against the host OS only — a name that is fine on Linux can break the moment the file syncs to a Windows client. These libraries close all of these gaps and compose cleanly.

The Core Pattern: Join a trusted root with untrusted parts, then move

The single most important pattern. Use pathologize.Join to combine a trusted root with untrusted path parts (regex captures, user input, scraped titles), then move with fileflow. Join sanitizes each part and guarantees it stays lexically under the root — a part can't inject an absolute path or ../ its way out.

import (
    "path/filepath"
 
    "github.com/spf13/fileflow"
    "github.com/spf13/pathologize"

fileflow.Move creates missing destination directories for you, so you do not need a separate os.MkdirAll.

fileflow

Safely move/copy/rename files, including across filesystems, without overwriting non-identical data. The package-level functions use the zero-value defaults; use a Flow when behavior must be configured per instance.

Functions

Move, Rename, and Copy all return the final destination path, which matters because of conflict handling below. Prefer Move over Rename unless you specifically want to fail across filesystems. Exists reports only an accessible regular file; it returns false for directories.

All three operations create missing destination directories by default. CopyWithPaths no longer exists because Copy itself now creates them.

Configure behavior with Flow

The zero value is ready to use. A nil FindAvailableName selects FindAvailableNameInc; a zero DirMode selects fileflow.DefaultDirMode (0o755). Set NoCreateDirs: true when destination directories must already exist—for example, when a destination is a required mount point and creating the path on the wrong volume would be dangerous. The operation then returns an error matching fs.ErrNotExist via errors.Is instead of creating the directory.

Flow also has Move, Rename, and Copy methods with the package-level signatures. Configure an instance before first use; do not mutate it while its methods may be running. Older mutable package globals are gone.

Conflict handling (the key feature)

When dst already exists, fileflow does not blindly overwrite:

• If the existing file is identical to the source → Copy leaves src untouched and returns dst without writing; Move/Rename remove src and return dst.
• If it differs → an incrementing suffix is added: photo.jpg → photo-1.jpg → photo-2.jpg, up to 100 candidates.

Always use the returned path; never assume the file landed at dst.

Naming strategies

Choose deliberately:

• FindAvailableNameInc (default): file-1.txt → file-1-1.txt and report-2024.txt → report-2024-1.txt.
• FindAvailableNameCont: file-1.txt → the next available sequence number, but also interprets report-2024.txt as a counter.
• FindAvailableNameAuto: continues one- or two-digit suffixes, while treating three or more digits as meaningful (report-2024-1.txt, not report-2025.txt).
• FindAvailableNameTS: appends 20060102-150405.000000000.

The 100-candidate limit is internal and not configurable.

Write safety and durability

• Rename uses no-replace primitives, so a racing writer cannot normally clobber an occupied destination. Windows uses MoveFileEx without replace; Unix uses atomic link-and-remove.
• On Unix filesystems without hard-link support (such as FAT and some network mounts), rename falls back to os.Rename; the no-overwrite guarantee is then best-effort.
• Copy writes to a temporary file in the destination directory, syncs it, preserves the source permission mode, and renames it into place with the same no-replace logic. A failed copy does not expose a partial destination or leave its temporary file behind.

Errors (errors.Is for sentinels, errors.As for structured errors)

ErrSameFile detects equivalent paths, symlinks, and case-only differences on case-insensitive filesystems—not just identical strings. Treat it as a no-op success only when that matches the caller's semantics. A removal error may return the final destination together with ErrFailedRemovingOriginal, because the content arrived safely but the source could not be deleted.

pathologize

Make a filename or path safe on every modern OS, not just the host. It is intentionally restrictive: strips illegal characters, trims trailing dots/spaces, enforces a 255-byte length, and neutralizes reserved names (CON → CON_).

Functions

Characters stripped by Clean: control chars plus \ / : * ? " < > |. Invalid UTF-8 becomes U+FFFD; leading/trailing whitespace and trailing dots are trimmed; names are capped at 255 bytes; reserved device names are defused (CON → CON_). Clean is idempotent and never returns an empty string (it falls back to "file").

Join — the safe way to build a destination (use this by default)

Join combines a trusted root with one or more untrusted parts:

• root is passed through verbatim — its separators, drive prefix, and trailing slash are preserved, and it is never sanitized. It must come from a trusted source (a configured destination, not user input).
• Each part is fully sanitized: split on both / and \, structural segments (empty, ., ..) dropped, every remaining segment run through Clean. A part that sanitizes to nothing contributes "file".
• The result is guaranteed to stay lexically under root — a part cannot escape it or inject an absolute path. This is the containment CleanPath does not provide.

CleanPath — make a full path valid (NOT safe)

CleanPath runs path.Clean semantics (collapse //, resolve . and internal .., drop a trailing separator) and additionally Cleans each component. In v1.1 it is volume-aware and separator-agnostic:

• Both / and \ are accepted as separators; output always uses /.
• A Windows drive prefix (C:) passes through verbatim.
• A UNC prefix (\\server\share) is preserved as //server/share.

CleanPath makes a path VALID, not SAFE. Like path.Clean, it preserves a leading .. in a relative path and keeps an absolute path absolute — it does not neutralize traversal or contain the result under any root. Use it only on paths you control (e.g. an author-configured absolute destination). For untrusted input, use Join, or Clean each segment yourself.

Security: path-traversal defense

Untrusted input must never decide where a file lands. Two safe options:

1. Join (preferred) — pass the trusted root and untrusted parts; parts are sanitized and contained under the root:

   dst := pathologize.Join(root, untrusted)   // can't escape root

2. Clean per segment — when you assemble the path yourself, Clean each untrusted segment before joining. Clean strips separators and resolves traversal tokens to a harmless single segment (".." → "file"), so a captured value can't introduce a new path level.

Do not rely on CleanPath for this — it preserves .. and absolute paths by design.

Common Mistakes

Installation

go get github.com/spf13/fileflow
go get github.com/spf13/pathologize