Skip to content

Files

Index

files::exists

Return true if the given path exists and is a regular file.

Arguments

  • $1 (file): path

files::assert_exists

Die if the given file does not exist.

Arguments

  • $1 (file): path

Exit codes

  • 0: if true
  • 1: if false

files::any_exists

Return true if the given path exists as any filesystem entry (regular file, directory, symlink, device, etc.).

Arguments

  • $1 (path): to test

Exit codes

  • 0: if true
  • 1: if false

files::is_executable

Return true if the given path is executable and is not a directory. Works for regular files and symlinks to regular files; returns false for directories, symlinks to directories, broken symlinks, and missing paths.

Arguments

  • $1 (file): path

Exit codes

  • 0: if true
  • 1: if false

files::assert_executable

Die if the given path is not executable or is a directory.

Arguments

  • $1 (file): path

files::is_empty

Return true if the given path exists, is a regular file, and has size zero.

Arguments

  • $1 (file): path

Exit codes

  • 0: if true
  • 1: if false

files::is_non_empty

Return true if the given path exists, is a regular file, and has size greater than zero.

Arguments

  • $1 (file): path

Exit codes

  • 0: if true
  • 1: if false

files::assert_empty

Die if the given file does not exist or is not empty.

Arguments

  • $1 (file): path

files::assert_non_empty

Die if the given file does not exist or has zero size.

Arguments

  • $1 (file): path

files::is_readable

Return true if the given file exists and is readable.

Arguments

  • $1 (file): path

Exit codes

  • 0: if true
  • 1: if false

files::size_gb

Print the size of a file in gigabytes (two decimal places). Output: stdout — size in GB, e.g. "1.23"

Arguments

  • $1 (file): path

files::mtime_epoch

Print the file's modification time as Unix epoch seconds.

Arguments

  • $1 (file): path

Output on stdout

  • epoch seconds

files::move

Move a file, prompting if the destination already exists; skips if source and dest are byte-identical.

Arguments

  • $1 (source): file path
  • $2 (destination): file path

files::move_quiet

Move a file quietly, prompting if the destination already exists; skips if source and dest are byte-identical. Like files::move but suppresses the "Moving/Moved" log messages.

Arguments

  • $1 (source): file path
  • $2 (destination): file path

files::move_no_prompt

Move a file without prompting, overwriting destination if it exists. For programmatic temp-file-to-dest moves where interactive confirmation would be inappropriate. Creates parent directory of destination if needed.

Arguments

  • $1 (source): file path
  • $2 (destination): file path

files::move_no_prompt_quiet

Move a file quietly without prompting, overwriting destination if it exists. Creates parent directory of destination if needed. Like files::move_no_prompt but suppresses the "Moving/Moved" log messages.

Arguments

  • $1 (source): file path
  • $2 (destination): file path

files::root_move

Move a file as root, prompting if the destination already exists; skips if byte-identical.

Arguments

  • $1 (source): file path
  • $2 (destination): file path

files::root_move_quiet

Move a file as root quietly, prompting if the destination already exists; skips if byte-identical. Like files::root_move but suppresses the "Moving/Moved" log messages.

Arguments

  • $1 (source): file path
  • $2 (destination): file path

files::copy

Copy a file, prompting if the destination already exists; skips if byte-identical.

Arguments

  • $1 (source): file path
  • $2 (destination): file path

files::copy_quiet

Copy a file quietly, prompting if the destination already exists; skips if byte-identical. Like files::copy but suppresses the "Copying/Copied" log messages.

Arguments

  • $1 (source): file path
  • $2 (destination): file path

files::root_copy

Copy a file as root, prompting if the destination already exists; skips if byte-identical.

Arguments

  • $1 (source): file path
  • $2 (destination): file path

files::root_copy_quiet

Copy a file as root quietly, prompting if the destination already exists; skips if byte-identical. Like files::root_copy but suppresses the "Copying/Copied" log messages.

Arguments

  • $1 (source): file path
  • $2 (destination): file path

files::root_transform

Transform a root-owned file by streaming it through a filter command. Reads the file via sudo cat, pipes the content through filter_cmd ..., and writes the result back via files::root_copy (which shows a diff and prompts before overwriting). Skips if the filtered output is byte-identical to the original. The filter command must read its input from stdin and write the transformed content to stdout. Bash functions defined in the calling shell are valid filters (they are inherited by the pipeline subshell).

Arguments

  • $1 (file): path to transform
  • ... (filter): command and any args

files::write

Write content to a file, prompting if the file already exists; skips if content is identical.

Arguments

  • $1 (file): path
  • $2 (content): to write

files::write_quiet

Write content to a file quietly, prompting if the file already exists; skips if content is identical. Like files::write but suppresses the "Writing/Wrote" log messages.

Arguments

  • $1 (file): path
  • $2 (content): to write

files::root_write

Write content to a root-owned file, prompting if the file already exists; skips if content is identical.

Arguments

  • $1 (file): path
  • $2 (content): to write

files::root_write_quiet

Write content to a root-owned file quietly, prompting if the file already exists; skips if content is identical. Like files::root_write but suppresses the "Writing/Wrote" log messages.

Arguments

  • $1 (file): path
  • $2 (content): to write

files::append_to

Append content to a file, creating the file and any missing parent directories as needed.

Arguments

  • $1 (file): path
  • $2 (content): to append

files::append_to_quiet

Append content to a file quietly, creating the file and any missing parent directories as needed. Like files::append_to but suppresses the "Appending/Appended" log messages.

Arguments

  • $1 (file): path
  • $2 (content): to append

files::root_append_to

Append content to a root-owned file, creating the file and any missing parent directories as needed.

Arguments

  • $1 (file): path
  • $2 (content): to append

files::root_append_to_quiet

Append content to a root-owned file quietly, creating the file and any missing parent directories as needed. Like files::root_append_to but suppresses the "Appending/Appended" log messages.

Arguments

  • $1 (file): path
  • $2 (content): to append

files::create_temp

Create a temporary file under /tmp and set the named variable in the caller's scope to its path. The file is NOT cleaned up on exit — /tmp is managed by the OS (tmpfs reboot wipe, systemd-tmpfiles age-based cleanup), so process-level cleanup is unnecessary and adds complexity (EXIT-trap clobbering, multi-file accounting).

Arguments

  • $1 (variable): name to receive the temp file path (nameref)

files::largest_files

Print the largest regular files under a directory, biggest first. Paths containing embedded newlines are not handled and may produce corrupt rows.

Arguments

  • $1 (dir): directory to scan
  • $2 (count): maximum number of rows to print

Output on stdout

  • tab-separated <bytes>\t<path> rows, largest first, at most rows

files::largest_dirs

Print the largest directories (cumulative apparent size) under a directory, biggest first. Paths containing embedded newlines are not handled and may produce corrupt rows.

Arguments

  • $1 (dir): directory to scan
  • $2 (count): maximum number of rows to print

Output on stdout

  • tab-separated <bytes>\t<path> rows, largest first, at most rows

files::largest_all

Print the largest entries (files and directories combined) under a directory, biggest first. Paths containing embedded newlines are not handled and may produce corrupt rows.

Arguments

  • $1 (dir): directory to scan
  • $2 (count): maximum number of rows to print

Output on stdout

  • tab-separated <bytes>\t<path> rows, largest first, at most rows

files::hash

Print the SHA-256 hash of a file or stdin. Dies if the file argument does not exist. Output: stdout — hex SHA-256 digest

Arguments

  • $1 (file): path (optional; reads stdin if omitted)

files::find_duplicates

Find files with identical content under a directory. Pre-filters by byte size (only files sharing a size are hashed), then groups survivors by SHA-256. Emits one tab-separated <bytes>\t<sha256>\t<path> line per file belonging to a duplicate set (>1 member), sorted by size descending then hash, so set members are contiguous. Paths containing embedded newlines or tab characters are not handled and may produce corrupt output rows. If a candidate file is removed between enumeration and hashing, files::hash dies (fail-loud) and aborts the scan.

Arguments

  • $1 (dir): optional directory to scan (default ".")

Output on stdout

  • tab-separated size\thash\tpath lines for duplicated files; empty if none

files::hash_if_exists

Print the SHA-256 hash of a file, or the empty string if the file does not exist. Intended for the "hash before / hash after" idiom where the destination file may not yet exist on first run. Output: stdout — hex SHA-256 digest, or empty string if the file is absent

Arguments

  • $1 (file): path

files::data_lines

Print the data lines of a line-oriented data file: every line except blank (empty or whitespace-only) lines and lines whose first character is #. Data lines are printed verbatim, so an indented # is data. A final line without a trailing newline is still printed.

Arguments

  • $1 (file): path to a line-oriented data file

Exit codes

  • 1: the file does not exist.

Output on stdout

  • One data line per line, in file order.

files::plan_renames

Compute a batch-rename plan. For each file, apply sed s/<pattern>/<replacement>/ to its basename (directory portion untouched). Emits surviving old\tnew pairs to stdout and warns (stderr) for each skip: no-op (unchanged name), destination already on disk, or a target duplicated within the batch. Pattern/replacement must not contain an unescaped / (sed s/// delimiter).

Arguments

  • $1 (pattern): sed BRE pattern matched against the basename
  • $2 (replacement): sed replacement string
  • ... (files): one or more file paths (after the first two args) to rename

Output on stdout

  • tab-separated old\tnew rename pairs for files that pass collision filtering

Output on stderr

  • a log::warn line for each skipped file