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