Skip to content

File Tools

⬅ Parent

Attributes

Modification time

fileModificationTime

Fetch the modification time of a file as a timestamp

Usage

fileModificationTime [ filename ... ]

Fetch the modification time of a file as a timestamp

Arguments

  • filename ... - File to fetch modification time

Examples

fileModificationTime ~/.bash_profile

Return codes

  • 2 - If file does not exist
  • 0 - If file exists and modification times are output, one per line

fileModificationSeconds

Fetch the modification time in seconds from now of a

Usage

fileModificationSeconds [ filename ... ]

Fetch the modification time in seconds from now of a file as a timestamp

Arguments

  • filename ... - File to fetch modification time

Examples

fileModificationTime ~/.bash_profile

Return codes

  • 2 - If file does not exist
  • 0 - If file exists and modification times are output, one per line

fileIsEmpty

Is this an empty (zero-sized) file?

Usage

fileIsEmpty [ file ] [ --help ]

Is this an empty (zero-sized) file?

Arguments

  • file - File. Optional. One or more files, all of which must be empty.
  • --help - Flag. Optional. Display this help.

Return codes

  • 0 - if all files passed in are empty files
  • 1 - if any files passed in are non-empty files

fileIsNewest

Check to see if the first file is the newest

Usage

fileIsNewest sourceFile [ targetFile ... ] [ --help ]

Check to see if the first file is the newest one If sourceFile is modified AFTER ALL targetFiles, return 0`` Otherwise return1``

Arguments

  • sourceFile - File. Required. File to check
  • targetFile ... - File. Optional. One or more files to compare. All must exist.
  • --help - Flag. Optional. Display this help.

Return codes

  • 1 - sourceFile, 'targetFile' does not exist, or
  • 0 - All files exist and sourceFile is the oldest file

fileIsOldest

Check to see if the first file is the newest

Usage

fileIsOldest sourceFile [ targetFile ... ] [ --help ]

Check to see if the first file is the newest one If sourceFile is modified AFTER ALL targetFiles, return 0`` Otherwise return1``

Arguments

  • sourceFile - File. Required. File to check
  • targetFile ... - File. Optional. One or more files to compare. All must exist.
  • --help - Flag. Optional. Display this help.

Return codes

  • 1 - sourceFile, 'targetFile' does not exist, or
  • 0 - All files exist and sourceFile is the oldest file

fileOldest

Output the oldest file in the list.

Usage

fileOldest file ... [ --help ]

Output the oldest file in the list.

Arguments

  • file ... - File. Required. One or more files to examine
  • --help - Flag. Optional. Display this help.

Return codes

  • 0 - Success
  • 1 - Environment error
  • 2 - Argument error

fileNewest

Output the newest file in the list

Usage

fileNewest file ... [ --help ]

Output the newest file in the list

Arguments

  • file ... - File. Required. One or more files to examine
  • --help - Flag. Optional. Display this help.

Return codes

  • 0 - Success
  • 1 - Environment error
  • 2 - Argument error

fileModifiedDays

Prints days (integer) since modified

Usage

fileModifiedDays file ... [ --help ]

Prints days (integer) since modified

Arguments

  • file ... - File. Required. One or more files to examine
  • --help - Flag. Optional. Display this help.

Return codes

  • 0 - Success
  • 2 - Can not get modification time

fileModifiedSeconds

Prints seconds since modified

Usage

fileModifiedSeconds file ... [ --help ]

Prints seconds since modified

Arguments

  • file ... - File. Required. One or more files to examine
  • --help - Flag. Optional. Display this help.

Return codes

  • 0 - Success
  • 2 - Can not get modification time

fileModificationTimes

Lists files in a directory recursively along with their modification

Usage

fileModificationTimes directory [ findArgs ]

Lists files in a directory recursively along with their modification time in seconds. Output is unsorted.

Arguments

  • directory - Directory. Required. Must exists - directory to list.
  • findArgs - Arguments. Optional. Optional additional arguments to modify the find query

Examples

fileModificationTimes $myDir ! -path "/./*"

Sample Output

1705347087 bin/build/tools.sh 1704312758 bin/build/deprecated.sh 1705442647 bin/build/build.json

Return codes

  • 0 - Success
  • 1 - Environment error
  • 2 - Argument error

fileModifiedRecently

List the most recently modified file in a directory prefixed

Usage

fileModifiedRecently directory [ findArgs ]

List the most recently modified file in a directory prefixed with the timestamp

Arguments

  • directory - Directory. Required. Must exists - directory to list.
  • findArgs - Arguments. Optional. Optional additional arguments to modify the find query

Return codes

  • 0 - Success
  • 1 - Environment error
  • 2 - Argument error

Owner Group Size Type

fileOwner

Get the file owner name

Usage

fileOwner [ file ] [ --help ]

Get the file owner name Outputs the file owner for each file passed on the command line

Arguments

  • file - File to get the owner for
  • --help - Flag. Optional. Display this help.

Return codes

  • 0 - Success
  • 1 - Unable to access file

fileGroup

Get the file group name

Usage

fileGroup [ file ] [ --help ]

Get the file group name Outputs the file group for each file passed on the command line

Arguments

  • file - File to get the owner for
  • --help - Flag. Optional. Display this help.

Return codes

  • 0 - Success
  • 1 - Unable to access file

fileSize

undocumented

Usage

fileSize [ file ... ] [ --help ]

No documentation for fileSize.

Reads standard input

File. One or more files to get size of.

Writes to standard output

UnsignedInteger

Arguments

  • file ... - Optional. One or more files to get size of.
  • --help - Flag. Optional. Display this help.

Return codes

  • 0 - Success
  • 1 - Environment error

fileType

Better type handling of shell objects

Usage

fileType [ item ] [ --help ]

Better type handling of shell objects Outputs one of type output or enhancements: - builtin, function, alias, file - link-directory, link-file, link-dead, directory, integer, unknown

Arguments

  • item - String. Optional. Thing to classify
  • --help - Flag. Optional. Display this help.

Return codes

  • 0 - Success
  • 1 - Environment error
  • 2 - Argument error

Platform

realPath

Find the full, actual path of a file avoiding symlinks

Usage

realPath file ...

Find the full, actual path of a file avoiding symlinks or redirection. Without arguments, displays help.

Arguments

  • file ... - File. Required. One or more files to realpath.

Return codes

  • 0 - Success
  • 1 - Environment error
  • 2 - Argument error

Requires

executableExists realpath __help usageDocument returnArgument

Utilities

Usage

fileDirectoryExists directory

Does the file's directory exist?

Arguments

  • directory - Directory. Required. Test if file directory exists (file does not have to exist)

Return codes

  • 0 - Success
  • 1 - Environment error
  • 2 - Argument error

fileTemporaryName

Wrapper for mktemp. Generate a temporary file name, and fail

Usage

fileTemporaryName handler [ --help ] [ ... ]

Wrapper for mktemp. Generate a temporary file name, and fail using a function

Arguments

  • handler - Function. Required. Function to call on failure. Function Type: returnMessage
  • --help - Flag. Optional. Display this help.
  • ... - Arguments. Optional. Any additional arguments are passed through.

Debugging settings

Append to the value of BUILD_DEBUG (a comma-delimited (,) list) and add these tokens to enable debugging:

  • temp - Logs backtrace of all temporary files to a file in application root named after this function to detect and clean up leaks

Return codes

  • 0 - Success
  • 1 - Environment error
  • 2 - Argument error

Environment

  • BUILD_DEBUG - CommaDelimitedList. Constant for turning debugging on during build to find errors in the build scripts. Enable debugging globally in the build scripts. Set to a comma (,) delimited list string to enable specific debugging, or true for ALL debugging, false (or blank) for NO debugging.

Requires

mktemp __help catchEnvironment usageDocument

filesRename

Rename a list of files usually to back them up temporarily

Usage

filesRename oldSuffix newSuffix actionVerb file ...

Renames "$file0$oldSuffix" to "$file0$newSuffix" if file exists and outputs a message using the actionVerb If files do not exist, does nothing Used to move files, temporarily, sometimes and then move back easily. Renames files which have oldSuffix to then have newSuffix and output a message using actionVerb:

Arguments

  • oldSuffix - String. Required. Old suffix to look rename from.
  • newSuffix - String. Required. New suffix to rename to.
  • actionVerb - String. Required. Description to output for found files.
  • file ... - String. Required. One or more files to rename, if found, renaming occurs.

Examples

filesRename "" ".$$.backup" hiding etc/app.json etc/config.json
...
filesRename ".$$.backup" "" restoring etc/app.json etc/config.json

Return codes

  • 0 - Success
  • 1 - Environment error
  • 2 - Argument error

fileReverseLines

Reverse output lines

Usage

fileReverseLines

Reverses a pipe's input lines to output using an awk trick. Not recommended on big files.

Arguments

  • none

Return codes

  • 0 - Success
  • 1 - Environment error
  • 2 - Argument error

Credits

Thanks to Eric Pement .

Usage

fileExtractLines startLine endLine [ --help ]

Extract a range of lines from a file

Reads standard input

Reads lines until EOF

Writes to standard output

Outputs the selected lines only

Arguments

  • startLine - Integer. Required. Starting line number.
  • endLine - Integer. Required. Ending line number.
  • --help - Flag. Optional. Display this help.

Return codes

  • 0 - Success
  • 1 - Environment error
  • 2 - Argument error

Usage

fileLineCount [ --help ] [ --handler handler ] [ file ]

Outputs the number of lines read from stdin (or supplied files) until EOF. For multiple files passed on the command line - each one is output separately. This is essentially a wrapper around wc -l which strips whitespace and does type checking.

Reads standard input

Lines are read from standard in and counted

Writes to standard output

UnsignedInteger UnsignedInteger

Arguments

  • --help - Flag. Optional. Display this help.
  • --handler handler - Function. Optional. Use this error handler instead of the default error handler.
  • file - File. Optional. Output line count for each file specified. If no files specified, uses stdin.

Return codes

  • 0 - Success
  • 1 - Environment error
  • 2 - Argument error

fileTeeAtomic

tee but atomic (EXPERIMENTAL)

Usage

fileTeeAtomic [ -a ] target [ --help ]

Write to a file in a single operation to avoid invalid files EXPERIMENTAL not a lot of testing of this don't use quite yet.

Reads standard input

Piped to a temporary file until EOF and then moved to target

Writes to standard output

A copy of stdin

Arguments

  • -a - Flag. Optional. Append target (atomically as well).
  • target - File. Required. File to target
  • --help - Flag. Optional. Display this help.

Return codes

  • 0 - Success
  • 1 - Environment error
  • 2 - Argument error

Finding

fileMatches

Find one or more patterns in a list of files,

Usage

fileMatches [ --help ] pattern ... -- [ exception ... ] -- file ...

Find one or more patterns in a list of files, with a list of file name pattern exceptions.

Arguments

  • --help - Flag. Optional. Display this help.
  • pattern ... - String. Required.grep -e Pattern to find in files. No quoting is added so ensure these are compatible with grep -e.
  • -- - Delimiter. Required. exception.
  • exception ... - String. Optional. grep -e File pattern which should be ignored.
  • -- - Delimiter. Required. file.
  • file ... - File. Required. File to search. Special file - indicates files should be read from stdin.

Return codes

  • 0 - Success
  • 1 - Environment error
  • 2 - Argument error

fileNotMatches

Find list of files which do NOT match a specific

Usage

fileNotMatches [ --help ] pattern ... -- [ exception ... ] -- file ...

Find list of files which do NOT match a specific pattern or patterns and output them

Arguments

  • --help - Flag. Optional. Display this help.
  • pattern ... - String. Required.grep -e Pattern to find in files.
  • -- - Delimiter. Required. exception.
  • exception ... - String. Optional. grep -e File pattern which should be ignored.
  • -- - Delimiter. Required. file.
  • file ... - File. Required. File to search. Special file - indicates files should be read from stdin.

Return codes

  • 0 - Success
  • 1 - Environment error
  • 2 - Argument error

linkCreate

Create a link

Usage

linkCreate [ target ] linkName

Create a link

Arguments

  • target - Exists. File. Source file name or path.
  • linkName - String. Required. Link short name, created next to target.

Return codes

  • 0 - Success
  • 1 - Environment error
  • 2 - Argument error

linkRename

Rename a link

Usage

linkRename from to

Rename a link Renames a link forcing replacement, and works on different versions of mv which differs between systems.

Arguments

  • from - Link. Required. Link to rename.
  • to - FileDirectory. Required. New link path.

Return codes

  • 0 - Success
  • 1 - Environment error
  • 2 - Argument error