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"
)

// destRoot is trusted (a configured directory); id/name are untrusted.
dstDir := pathologize.Join(destRoot, "ig", id)   // parts sanitized + contained
dst := filepath.Join(dstDir, filepath.Base(src))

final, err := fileflow.Move(src, dst)            // cross-fs safe, conflict safe
if err != nil {
    return err
}
// final is where the file actually landed (may be suffixed on conflict).

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

func Move(src, dst string) (string, error)          // rename if same FS, else copy+delete
func Rename(src, dst string) (string, error)         // same-FS only; fails on cross-device
func Copy(src, dst string) (string, error)           // atomic copy; returns final path
func Exists(path string) bool
func Equal(file1, file2 string) (bool, error)        // byte-for-byte comparison

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

type Flow struct {
    FindAvailableName func(string) (string, error)
    DirMode           fs.FileMode
    NoCreateDirs      bool
}

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.

f := fileflow.Flow{
    FindAvailableName: fileflow.FindAvailableNameAuto,
    DirMode:           0o700,
    NoCreateDirs:      true,
}

final, err := f.Move(src, dst)

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

// Default: preserve the full requested name, then append -1, -2, ...
f := fileflow.Flow{FindAvailableName: fileflow.FindAvailableNameInc}

// Continue a trailing one-or-more-digit counter: file-3.txt -> file-4.txt.
f.FindAvailableName = fileflow.FindAvailableNameCont

// Continue one- or two-digit counters, but preserve years/zero-padded IDs.
f.FindAvailableName = fileflow.FindAvailableNameAuto

// Append a nanosecond timestamp; fall back to incrementing on collision.
f.FindAvailableName = fileflow.FindAvailableNameTS

// Or supply any func(baseName string) (string, error).
f.FindAvailableName = myStrategy

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)

fileflow.ErrSameFile             // src and dst are the same file
fileflow.ErrMaxAttemptsReached   // ran out of conflict-suffix attempts
*fileflow.ErrFailedMovingFile    // fields: Src, Dst, Err
*fileflow.ErrFailedRemovingOriginal // fields: File, Err

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

func Clean(filename string) string          // sanitize ONE name/segment
func CleanPath(path string) string          // make a full path VALID (volume-aware)
func Join(root string, parts ...string) string // trusted root + untrusted parts, contained
func IsClean(filename string) bool          // true if Clean(name) == name

pathologize.Clean("CON..")            // "CON_"
pathologize.Clean("a/b:c*d?.txt")     // "abcd.txt"  (/, :, *, ? are illegal)

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)

func Join(root string, parts ...string) string

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.

pathologize.Join("/data", "../../etc", "pass:wd")   // "/data/etc/passwd" — contained + cleaned
pathologize.Join(`C:\Sorted`, "ig", userName)       // root verbatim, userName sanitized

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.

pathologize.CleanPath(`C:\Users\me\report:final`) // "C:/Users/me/reportfinal"
pathologize.CleanPath("a//b/../c")                 // "a/c"

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

Mistake	Fix
os.Rename across volumes → EXDEV	fileflow.Move (copy+delete fallback)
Assuming the file landed at dst	Use the path returned by Move/Rename/Copy
Overwriting existing files	fileflow already suffixes non-identical files — don't pre-check
Setting old package globals	Configure a fileflow.Flow; the mutable globals were removed
Calling removed CopyWithPaths	Use Copy; it creates parent directories by default
Requiring a mount point but allowing directory creation	Use Flow{NoCreateDirs: true}
Building a dest from untrusted input by hand	pathologize.Join(root, parts...) — sanitized + contained
Using CleanPath on untrusted input	CleanPath makes paths VALID, not SAFE — use Join
Sanitizing the trusted root too	Join takes root verbatim; only parts are untrusted
Manual os.MkdirAll before an operation	Move/Rename/Copy create parents by default

Installation

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