Skip to content

File Tools

⬅ Parent

Attributes

Modification time

fileModificationTime

Fetch the modification time of a file as a timestamp

Usage

fileModificationTime filename0 [ filename1 ... ]

Fetch the modification time of a file as a timestamp

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

Arguments

  • none

Examples

fileModificationTime ~/.bash_profile

Return codes

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

fileModificationSeconds

Fetch the modification time in seconds from now of a

Usage

fileModificationSeconds filename0 [ filename1 ... ]

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

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

Arguments

  • none

Examples

fileModificationTime ~/.bash_profile

Return codes

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

fileIsEmpty

Is this an empty (zero-sized) file?

Usage

fileIsEmpty [ file ] [ --help ]

Is this an empty (zero-sized) file? Return Code: 0 - if all files passed in are empty files Return Code: 1 - if any files passed in are non-empty files

Arguments

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

Return codes

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

fileIsNewest

Check to see if the first file is the newest

Usage

fileIsNewest firstFile [ targetFile0 ... ]

Check to see if the first file is the newest one

If sourceFile is modified AFTER ALL targetFiles, return 0`` Otherwise return1``

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

Arguments

  • sourceFile - File to check
  • targetFile0 - One or more files to compare

Return codes

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

fileIsOldest

Check to see if the first file is the newest

Usage

fileIsOldest firstFile [ targetFile0 ... ]

Check to see if the first file is the newest one

If sourceFile is modified AFTER ALL targetFiles, return 0`` Otherwise return1``

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

Arguments

  • sourceFile - File to check
  • targetFile0 - One or more files to compare

Return codes

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

fileOldest

Return the oldest file in the list.

Usage

fileOldest file0 [ file1 ... ]

Return the oldest file in the list.

Arguments

  • file0 - One or more files to examine

Return codes

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

fileNewest

Return the newest file in the list

Usage

fileNewest file0 [ file1 ... ]

Return the newest file in the list

Arguments

  • file0 - One or more files to examine

Return codes

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

fileModifiedDays

Prints days (integer) since modified

Usage

fileModifiedDays

Prints days (integer) since modified

Return Code: 0 - Success Return Code: 2 - Can not get modification time

Arguments

  • none

Return codes

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

fileModifiedSeconds

Prints seconds since modified

Usage

fileModifiedSeconds file

Prints seconds since modified Return Code: 0 - Success Return Code: 2 - Can not get modification time

Arguments

  • none

Return codes

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

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 - Required. Directory. Must exists - directory to list.
  • findArgs - 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 - Required. Directory. Must exists - directory to list.
  • findArgs - Optional additional arguments to modify the find query

Return codes

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

Owner Group Size Type

fileOwner

Outputs the file owner for each file passed on the

Usage

fileOwner file ...

Outputs the file owner for each file passed on the command line Return Code: 0 - Success Return Code: 1 - Unable to access file

Arguments

  • file - File to get the owner for

Return codes

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

fileGroup

Outputs the file group for each file passed on the

Usage

fileGroup file ...

Outputs the file group for each file passed on the command line Return Code: 0 - Success Return Code: 1 - Unable to access file

Arguments

  • file - File to get the owner for

Return codes

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

fileSize

Outputs value of virtual memory allocated for a process, value

Usage

fileSize file

Outputs value of virtual memory allocated for a process, value is in kilobytes Return Code: 0 - Success Return Code: 1 - Environment error

Arguments

  • file - Required. File to get size of.

Return codes

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

fileType

Better type handling of shell objects

Usage

fileType [ item ]

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

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 ... - Required. File. One or more files to realpath.

Return codes

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

Requires

whichExists realpath __help usageDocument returnArgument

Utilities

fileDirectoryExists

Does the file's directory exist?

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 - Optional. Flag. Display this help.
  • ... - Optional. Arguments. 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 file0 [ file1 file2 ... ]

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 - Required. String. Old suffix to look rename from.
  • newSuffix - Required. String. New suffix to rename to.
  • actionVerb - Required. String. Description to output for found files.
  • file0 - Required. String. 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 .

fileExtractLines

Extract a range of lines from a file

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 - Optional. Flag. Display this help.

Return codes

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

fileLineCount

Outputs the number of lines read from stdin (or supplied

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

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 - Optional. Flag. Display this help.
  • pattern ... - Required. String. Pattern to find in files. No quoting is added so ensure these are compatible with grep -e.
  • -- - Required. Delimiter. exception.
  • exception ... - Optional. String. File pattern which should be ignored.
  • -- - Required. Delimiter. file.
  • file ... - Required. File. 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 - Optional. Flag. Display this help.
  • pattern ... - Required. String. Pattern to find in files.
  • -- - Required. Delimiter. exception.
  • exception ... - Optional. String. File pattern which should be ignored.
  • -- - Required. Delimiter. file.
  • file ... - Required. File. 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

Renames a link forcing replacement, and works on different versions

Usage

linkRename from to

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

Arguments

  • none

Return codes

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