Documentation

• 1: Framework Guides
• 1.1: Configuration Files
• 1.2: Docker Namespace
• 1.3: Best Practices
• 2: Namespace
• 2.1: Namespace src/Args
• 2.2: Namespace src/Array
• 2.3: Namespace src/Assert
• 2.4: Namespace src/Aws
• 2.5: Namespace src/Backup
• 2.6: Namespace src/Bash
• 2.7: Namespace src/Bats
• 2.8: Namespace src/Cache
• 2.9: Namespace src/Command
• 2.10: Namespace Compiler
• 2.10.1: Namespace src/Compiler/Embed
• 2.11: Namespace src/Conf
• 2.12: Namespace src/Crypto
• 2.13: Namespace src/Database
• 2.14: Namespace src/Dns
• 2.15: Namespace src/Docker
• 2.16: Namespace src/Env
• 2.17: Namespace src/File
• 2.18: Namespace src/Filters
• 2.19: Namespace src/Framework
• 2.20: Namespace src/Git
• 2.21: Namespace src/Github
• 2.22: Namespace src/Install
• 2.23: Namespace Linux
• 2.23.1: Namespace src/Linux/Apt
• 2.23.2: Namespace src/Linux/Sudo
• 2.23.3: Namespace src/Linux/Wsl
• 2.24: Namespace src/Log
• 2.25: Namespace src/Profiles
• 2.26: Namespace src/Retry
• 2.27: Namespace src/ShellDoc
• 2.28: Namespace src/Softwares
• 2.29: Namespace src/Ssh
• 2.30: Namespace src/UI
• 2.31: Namespace src/Version
• 2.32: Namespace src/Web
• 3: Framework Overview
• 4: Commands

1 - Framework Guides

General framework documentation explaining main framework features:

• Configuration files loading management
• Docker namespace usage
• Best practices and recipes

For creating your first binary file, see the Commands documentation.

1.1 - Configuration Files

Inspired by Evan “Hippy” Slatis work

1. Config file format and loading rules

Configuration files loading is following these rules or best practices:

• all env files are now loaded as properties file, it means bash arrays cannot be declared Eg: arrays should be converted to a string list separated by colon, and has to converted when needed.
• All .env files have the ability to override value by env variable
• all variables have to be written on one line, it is not possible to cut lines over multiple line
• First variable set takes precedence, so writing following file would result to VAR1=value1

VAR1=value1
VAR1=value2

2. Config file overloading values

• Best practice is to override variables only by
  • command argument –bash-framework-config to allow loading alternate env before other default files
  • command argument (–verbose, …) allows to override default displayed log level
  • in env files, always allow value to be overridden by prioritized variables
    • using bash variable default value mechanism, in following example, BASH_FRAMEWORK_LOG_LEVEL will be equal to 0 only if it hasn’t been set previously

BASH_FRAMEWORK_LOG_LEVEL="${BASH_FRAMEWORK_LOG_LEVEL:-0}"

• Provide –config argument to see resulting config file + information about order of loaded config files for debugging purpose.

• It is also possible to use environment variable, but highly discouraged to generalize this practice as it could lead to unwanted results if variables are not well scoped.

3. Config files loading order

The framework function Env::requireLoad loads the following files in this order if they are existing and are readable:

• files provided in BASH_FRAMEWORK_ENV_FILES env variable array
• ${FRAMEWORK_ROOT_DIR}/.framework-config if exists
• .framework-config from current directory if exists
• file from option –bash-framework-config

Options can override values provided by these env files:

• if –verbose or -v argument is passed, set BASH_FRAMEWORK_DISPLAY_LEVEL to 3 (INFO)
• if -vv argument is passed, set BASH_FRAMEWORK_DISPLAY_LEVEL to 4 (DEBUG)
• later on, will manage other kind of arguments
• additional files provided by this bash array variable, see below.
• framework default values file, see below.

Eg: additional environment files

BASH_FRAMEWORK_ENV_FILES=("${HOME}/.bash-tools/.env" "${HOME}/.env")

Eg: framework default values file

BASH_FRAMEWORK_LOG_LEVEL="${BASH_FRAMEWORK_LOG_LEVEL:-0}"
BASH_FRAMEWORK_DISPLAY_LEVEL="${BASH_FRAMEWORK_DISPLAY_LEVEL:-${__LEVEL_WARNING}}"
BASH_FRAMEWORK_LOG_FILE="${BASH_FRAMEWORK_LOG_FILE:-"${FRAMEWORK_ROOT_DIR}/logs/${SCRIPT_NAME}.log"}"
BASH_FRAMEWORK_LOG_FILE_MAX_ROTATION="${BASH_FRAMEWORK_LOG_FILE_MAX_ROTATION:-5}"

Activity diagram to explain how Env::requireLoad is working:

activity diagram source code.

1.2 - Docker Namespace

Usage example: try to pull image from 3 tags in order (from more specific or recent to the less one)

# try to pull image from 3 tags in order (from more specific or recent to the less one)
args=(
  'id.dkr.ecr.eu-west-1.amazonaws.com/bash-tools:d93e03d5ab9e127647f575855f605bd189ca8a56'
  'id.dkr.ecr.eu-west-1.amazonaws.com/bash-tools:branchName'
  'id.dkr.ecr.eu-west-1.amazonaws.com/bash-tools:master'
)
digestPulled="$(Docker::pullImage "${args[@]}")"

# build the image using eventual image pulled as cache
# image will be tagged bash-tools:latest upon successful build
args=(
  "." ".docker/Dockerfile" "bash-tools"
  # it's important to not double quote following instruction
  $(Docker::getBuildCacheFromArg ${digestPulled})
  # you can add any additional docker build arg as needed
  --build-arg USER_ID="$(id -u)"
  --build-arg GROUP_ID="$(id -g)"
)
Docker::buildImage "${args[@]}"

# tag the image with a remote tag
args=(
  "id.dkr.ecr.eu-west-1.amazonaws.com/bash-tools"
  "bash-tools:latest"
  # tags list
  "branchName" "d93e03d5ab9e127647f575855f605bd189ca8a56"
)
Docker::tagImage "${args[@]}"

# finally push the image
args=(
  "id.dkr.ecr.eu-west-1.amazonaws.com/bash-tools"
  "bash-tools:latest"
  # tags list
  "branchName" "d93e03d5ab9e127647f575855f605bd189ca8a56"
)
Docker::pushImage "${args[@]}"

1.3 - Best Practices

DISCLAIMER: Some of the best practices mentioned are not fully applied in this project as they were written during development.

1. Framework-Specific Recommendations

1.1. Using @embed Keyword

The @embed keyword is really useful to inline configuration files. However, to run framework functions using sudo, it is recommended to call the same binary but passing options to change the behavior. This way the content of the script file does not seem to be obfuscated.

1.2. Function Organization

Follow the framework’s naming conventions:

• Use Namespace::functionName pattern
• Place functions in appropriate namespace directories
• Include comprehensive documentation using shdoc annotations
• Write unit tests for every function

1.3. Testing Strategy

• Run tests on multiple Bash versions (4.4, 5.0, 5.3)
• Test on both Ubuntu and Alpine environments
• Use # bats test_tags=ubuntu_only for Ubuntu-specific tests
• Leverage stub/mock capabilities for external dependencies

2 - Namespace

2.1 - Namespace src/Args

src/Args

Overview

Directory src/Args

file source src/Args/defaultHelp.sh

Args::defaultHelp

display help and exits if one of args is -h|–help

Options

• -h

  short help option

• –help

  long help option

Arguments

• $1 (helpArg:String|Function): the help string to display or the function to call to display the help
• … (args:String[]): list of options

Exit codes

• 0: displays help and exit with code 0 if -h or –help option is in the args list

Output on stdout

• displays help if -h or –help option is in the args list

src/Args/defaultHelpNoExit.sh

file source src/Args/defaultHelpNoExit.sh

Args::defaultHelpNoExit

display help if one of args is -h|–help

Options

• -h

  short help option

• –help

  long help option

Arguments

• $1 (helpArg:String|Function): the help string to display or the function to call to display the help
• … (args:String[]): list of options

Exit codes

• 1: displays help and returns with code 1 if -h or –help option is in the args list

Output on stdout

• displays help if -h or –help option is in the args list

src/Args/showHelp.sh

file source src/Args/showHelp.sh

Args::showHelp

display help

Arguments

• $1 (helpArg:String): the help string to show

Output on stdout

• display help arg

2.2 - Namespace src/Array

src/Array

Overview

Directory src/Array

file source src/Array/clone.sh

Array::clone

clone the array passed as parameter

Arguments

• $1 (arrayToClone:String): name of the array to clone
• $2 (clonedArray:String): name of the cloned array

Variables set

• clonedArray (containing): the values of arrayToClone

src/Array/contains.sh

file source src/Array/contains.sh

Array::contains

check if an element is contained in an array

Example

Array::contains "${libPath}" "${__BASH_FRAMEWORK_IMPORTED_FILES[@]}"

Arguments

• $1 needle:String
• $@ array:String[]

Exit codes

• 0: if found
• 1: otherwise

src/Array/join.sh

file source src/Array/join.sh

Array::join

concatenate each element of an array with a separator

Example

declare -a array=(test1, test2)
echo "Result= $(Array::join "," "${array[@]})"
Result= test1,test2

Arguments

• $1 glue:String
• $@ array:String[]

src/Array/remove.sh

file source src/Array/remove.sh

Array::remove

remove elements from array

Arguments

• $1 (arrayRemoveArray:&String[]): (reference) array from which elements have to be removed
• … (valuesToRemoveKeys:String[]): list of elements to remove

Warnings

• Performance1 : version taken from https://stackoverflow.com/a/59030460
• Performance2 : for multiple values to remove, prefer using Array::removeIf

See also

• Array::removeIf

src/Array/removeIf.sh

file source src/Array/removeIf.sh

Array::removeIf

more performant version of Array:remove remove elements from array using a predicate function

Example

function predicateElem1to5() {
  [[ "$1" =~ ^elem[1-5]$ ]] || return 1
}
local -a myArray=("elem1" "elemX" "elem2" "elemX" "elem3" "elemX" "elem4" "elemX" "elem5" "elemX")
Array::removeIf myArray predicateElem1to5
echo "Result: ${myArray[*]}"
## Result: elemX elemX elemX elemX elemX

Arguments

• $1 (arrayRemoveArray:&String[]): (reference) array from which elements have to be removed
• $2 (predicateFunction:Function): callback function called on each element

Exit codes

• 1: if predicateFunction argument is not a function or empty

See also

• Array::remove

src/Array/wrap.sh

file source src/Array/wrap.sh

Array::wrap

concatenate each element of an array with a separator but wrapping text when line length is more than provided argument The algorithm will try not to cut the array element if can

Arguments

• $1 glue:String
• $2 maxLineLength:int
• $3 indentNextLine:int
• $@ array:String[]

src/Array/wrap2.sh

file source src/Array/wrap2.sh

Array::wrap2

concatenate each element of an array with a separator but wrapping text when line length is more than provided argument The algorithm will try not to cut the array element if it can.

• if an arg can be placed on current line it will be, otherwise current line is printed and arg is added to the new current line
• Empty arg is interpreted as a new line.
• Add \r to arg in order to force break line and avoid following arg to be concatenated with current arg.

Arguments

• $1 glue:String
• $2 maxLineLength:int
• $3 indentNextLine:int
• $@ array:String[]

2.3 - Namespace src/Assert

src/Assert

Overview

Directory src/Assert

file source src/Assert/bashFile.sh

Assert::bashFile

ensure that file begin with a bash shebang

Arguments

• $1 file:String

Exit codes

• 1: if file doesn’t have a bash shebang
• 2: if file doesn’t exist

src/Assert/bashFrameworkFunction.sh

file source src/Assert/bashFrameworkFunction.sh

Assert::bashFrameworkFunction

assert that first arg respects this bash framework naming convention

Arguments

• $1 (bashFrameworkFunction:String): the function’s name to assert

Exit codes

• 1: if bashFrameworkFunction arg doesn’t respect this bash framework naming convention

src/Assert/commandExists.sh

file source src/Assert/commandExists.sh

Assert::commandExists

check if command specified exists or return 1 with error and message if not

Arguments

• $1 (commandName:String): on which existence must be checked
• $2 (helpIfNotExists:String): a help command to display if the command does not exist

Exit codes

• 1: if the command specified does not exist

Output on stderr

• diagnostic information + help if second argument is provided

src/Assert/curlPingWithRetry.sh

file source src/Assert/curlPingWithRetry.sh

Assert::curlPingWithRetry

check if ulr provided can be reached (trying if failure)

Arguments

• $1 (url:String): the url to contact using curl
• $2 (title:String): the title to pass to Retry::parameterized method (default: “Try to contact ${title} …”)
• $3 (maxRetries:int): max retries (default: 40)
• $4 (delayBetweenTries:int): delay between attempt in seconds (default value: 5 seconds)

Output on stderr

• progression status using title argument

Requires

• Linux::requireCurlCommand

Features

• Retry::parameterized

src/Assert/dirEmpty.sh

file source src/Assert/dirEmpty.sh

Assert::dirEmpty

asserts that directory does not exist check if directory empty using ls -A if pattern provided, apply grep -v with this pattern on ls -A result

Arguments

• $1 directory:String
• $2 (pattern:String): list of files considered to be present in the directory

Environment variables

• SUDO (String): allows to use custom sudo prefix command
• SUDO (String): allows to use custom sudo prefix command

Exit codes

• 1: directory does not exists
• 2: directory arg is actually a file
• 3: directory not empty

Output on stderr

• diagnostics information is displayed

src/Assert/dirExists.sh

file source src/Assert/dirExists.sh

Assert::dirExists

asserts that first argument is directory that exists with specified ownership

Arguments

• $1 dir:String
• $2 (user:String): expected owner user name of the directory (default: USERNAME or id -un command)
• $3 (group:String): expected owner group name of the directory (default: USERGROUP or id -gn command)

Environment variables

• USERNAME (String): if arg $2 is not provided
• USERGROUP (String): if arg $3 is not provided

Exit codes

• 1: if missing directory
• 2: if incorrect user ownership
• 3: if incorrect group ownership

Output on stderr

• diagnostics information is displayed

src/Assert/dirNotExists.sh

file source src/Assert/dirNotExists.sh

Assert::dirNotExists

asserts that directory does not exist

Arguments

• $1 dir:String

Environment variables

• SUDO (String): allows to use custom sudo prefix command
• SUDO (String): allows to use custom sudo prefix command

Exit codes

• 1: existing dir

Output on stderr

• diagnostics information is displayed

src/Assert/dnsHostname.sh

file source src/Assert/dnsHostname.sh

Assert::dnsHostname

check if param is valid dns hostname

Arguments

• $1 (dnsHostname:String): the dns hostname

Exit codes

• 1: if invalid hostname

src/Assert/emailAddress.sh

file source src/Assert/emailAddress.sh

Assert::emailAddress

check if param is valid email address

Arguments

• $1 (emailAddress:String): the full email address

Exit codes

• 1: if invalid email address

Warnings

• it is a very simple check, no RFC validation

src/Assert/emailAddressWithDomain.sh

file source src/Assert/emailAddressWithDomain.sh

Assert::emailAddressWithDomain

check if param is valid email address with one the specified domains

Arguments

• $1 (email:String): the full email address
• … (expectedDomains:String[]): the expected email address domains (no check if empty)

Exit codes

• 1: if email invalid
• 2: if email domain doesn’t match the expected domains passed in arguments

Warnings

• it is a very simple check, no RFC validation

See also

• Assert::emailAddress

src/Assert/etcHost.sh

file source src/Assert/etcHost.sh

Assert::etcHost

Check if Host is defined in etc/hosts of linux and windows (if applicable)

Arguments

• $1 host:String

Exit codes

• 1: if /etc/hosts doesn’t exist in linux
• 2: if host doesn’t exist in linux /etc/hosts
• 3: if host doesn’t exist in windows etc/hosts or windows etc/hosts doesn’t exists

Output on stderr

• diagnostics information is displayed

See also

• Linux::Wsl::assertWindowsEtcHost

src/Assert/expectGlobalVariables.sh

file source src/Assert/expectGlobalVariables.sh

Assert::expectGlobalVariables

exits with message if expected global variable is not set

Example

Assert::expectGlobalVariables EXISTING_VAR EXISTING_VAR2

Arguments

• … (expectedGlobals:String[]): expected global variables

Exit codes

• 1: if one of the expected global variables is not set

Output on stderr

• diagnostics information displayed

src/Assert/expectNonRootUser.sh

file source src/Assert/expectNonRootUser.sh

Assert::expectNonRootUser

exits with message if current user is root

Function has no arguments.

Exit codes

• 1: if current user is root

Output on stderr

• diagnostics information is displayed

src/Assert/expectUser.sh

file source src/Assert/expectUser.sh

Assert::expectUser

exits with message if current user is not the expected one

Arguments

• $1 (expectedUserName:String): expected user login

Exit codes

• 1: if current user is not the expected one

Output on stderr

• diagnostics information is displayed

src/Assert/fileExecutable.sh

file source src/Assert/fileExecutable.sh

Assert::fileExecutable

asserts that first argument is a file that exists with specified ownership and is executable

Arguments

• $1 file:String
• $2 (user:String): expected owner user name of the file (default: USERNAME or id -un command)
• $3 (group:String): expected owner group name of the file (default: USERGROUP or id -gn command)

Environment variables

• USERNAME (String): if arg $2 is not provided
• USERGROUP (String): if arg $3 is not provided

Exit codes

• 1: if Assert::fileExists fails
• 2: if file is not executable

Output on stderr

• diagnostics information is displayed

See also

• Assert::fileExists

src/Assert/fileExists.sh

file source src/Assert/fileExists.sh

Assert::fileExists

asserts that first argument is file that exists with specified ownership

Arguments

• $1 file:String
• $2 (user:String): expected owner user name of the file (default: USERNAME or id -un command)
• $3 (group:String): expected owner group name of the file (default: USERGROUP or id -gn command)

Environment variables

• USERNAME (String): if arg $2 is not provided
• USERGROUP (String): if arg $3 is not provided
• SUDO (String): allows to use custom sudo prefix command

Exit codes

• 1: if missing file
• 2: if incorrect user ownership
• 3: if incorrect group ownership

Output on stderr

• diagnostics information is displayed

src/Assert/fileNotExecutable.sh

file source src/Assert/fileNotExecutable.sh

Assert::fileNotExecutable

asserts that first argument is a file that exists with specified ownership and is NOT executable

Arguments

• $1 file:String
• $2 (user:String): expected owner user name of the file (default: USERNAME or id -un command)
• $3 (group:String): expected owner group name of the file (default: USERGROUP or id -gn command)

Environment variables

• USERNAME (String): if arg $2 is not provided
• USERGROUP (String): if arg $3 is not provided

Exit codes

• 1: if Assert::fileExists fails
• 2: if file is executable

Output on stderr

• diagnostics information is displayed

See also

• Assert::fileExists

src/Assert/fileNotExists.sh

file source src/Assert/fileNotExists.sh

Assert::fileNotExists

asserts that file does not exist

Arguments

• $1 file:String

Environment variables

• SUDO (String): allows to use custom sudo prefix command
• SUDO (String): allows to use custom sudo prefix command

Exit codes

• 1: existing file

Output on stderr

• diagnostics information is displayed

src/Assert/fileWritable.sh

file source src/Assert/fileWritable.sh

Assert::fileWritable

Checks if file can be created in folder The file does not need to exist

Arguments

• $1 file:String

Exit codes

• 1: if file is not a valid path
• 2: if file parent’s dir is not writable
• 3: if existing file is not writable

See also

• Assert::validPath

src/Assert/firstNameLastName.sh

file source src/Assert/firstNameLastName.sh

Assert::firstNameLastName

check if argument respects 2 or more words separated by a space it supports accentuated characters and names with hyphen(-)

Arguments

• $1 firstNameLastName:String

Exit codes

• 1: if regexp not matches

See also

• https://regex101.com/r/JyyfOM/1

src/Assert/functionExists.sh

file source src/Assert/functionExists.sh

Assert::functionExists

checks if function name provided exists

Arguments

• $1 functionName:String

Exit codes

• 1: if function name doesn’t exist

src/Assert/ldapLogin.sh

file source src/Assert/ldapLogin.sh

Assert::ldapLogin

check if argument respects ldap login naming convention only using lowercase characters a-z

Arguments

• $1 ldapLogin:String

Exit codes

• 1: if regexp not matches

src/Assert/posixFunctionName.sh

file source src/Assert/posixFunctionName.sh

Assert::posixFunctionName

assert that first arg respects posix function naming convention

Arguments

• $1 (posixFunctionName:String): the function’s name to assert

Exit codes

• 1: if posixFunctionName arg doesn’t respect posix function naming convention

src/Assert/symLinkValid.sh

file source src/Assert/symLinkValid.sh

Assert::symLinkValid

asserts that first argument is link to a file that exists

Arguments

• $1 (link:String): expected link

Environment variables

• SUDO (String): allows to use custom sudo prefix command

Exit codes

• 1: if missing link
• 2: if not a link
• 3: if broken link (missing linked file)

Output on stderr

• diagnostics information is displayed

src/Assert/tty.sh

file source src/Assert/tty.sh

Assert::tty

check if tty (interactive mode) is active

Function has no arguments.

Environment variables

• NON_INTERACTIVE (if): 1 consider as not interactive even if environment is interactive
• INTERACTIVE (if): 1 consider as interactive even if environment is not interactive

Exit codes

• 1: if tty not active

src/Assert/validPath.sh

file source src/Assert/validPath.sh

Assert::validPath

check if argument is a valid linux path invalid path are those with:

• invalid characters
• component beginning by a - (because could be considered as a command’s option)
• not beginning with a slash
• relative

Arguments

• $1 (path:string): path that needs to be checked

Exit codes

• 1: if path is invalid

See also

• https://regex101.com/r/afLrmM/2
• Assert::validPosixPath if you need more restrictive check

src/Assert/validPosixPath.sh

file source src/Assert/validPosixPath.sh

Assert::validPosixPath

check if argument is a valid posix linux path and does not contains relative directory

Arguments

• $1 (path:string): path that needs to be checked

Exit codes

• 1: if path is invalid

Requires

• Linux::requirePathchkCommand
• Linux::requireRealpathCommand

Warnings

• posix path is really restrictive, if you need less restrictive check you can use Assert::validPath

src/Assert/validVariableName.sh

file source src/Assert/validVariableName.sh

Assert::validVariableName

check if argument respects this framework variable naming convention

• if variable begins with an uppercase or underscore, following letters have to be uppercase or underscore
• variable name can includes ‘:’ or ‘_’ or digits but not as first letter here valid variable name examples

Arguments

• $1 variableName:String

Exit codes

• 1: if regexp not matches

See also

• https://regex101.com/r/BUlPXS/1

src/Assert/varExistsAndNotEmpty.sh

file source src/Assert/varExistsAndNotEmpty.sh

Assert::varExistsAndNotEmpty

checks if variable name provided exists

Arguments

• $1 varName:String

Exit codes

• 1: if variable doesn’t exist
• 2: if variable value empty
• 3: if variable name invalid

Output on stderr

• diagnostics information is displayed

See also

• Assert::validVariableName

src/Assert/windows.sh

file source src/Assert/windows.sh

Assert::windows

determine if the script is executed under windows (using wsl)

Example

uname GitBash windows (with wsl) => MINGW64_NT-10.0 ZOXFL-6619QN2 2.10.0(0.325/5/3) 2018-06-13 23:34 x86_64 Msys
uname GitBash windows (wo wsl)   => MINGW64_NT-10.0 frsa02-j5cbkc2 2.9.0(0.318/5/3) 2018-01-12 23:37 x86_64 Msys
uname wsl => Linux ZOXFL-6619QN2 4.4.0-17134-Microsoft #112-Microsoft Thu Jun 07 22:57:00 PST 2018 x86_64 x86_64 x86_64 GNU/Linux

Exit codes

• 1: on error

src/Assert/wsl.sh

file source src/Assert/wsl.sh

Assert::wsl

determine if the script is executed under WSL

Example

uname GitBash windows (with wsl) => MINGW64_NT-10.0 ZOXFL-6619QN2 2.10.0(0.325/5/3) 2018-06-13 23:34 x86_64 Msys
uname GitBash windows (wo wsl)   => MINGW64_NT-10.0 frsa02-j5cbkc2 2.9.0(0.318/5/3) 2018-01-12 23:37 x86_64 Msys
uname wsl => Linux ZOXFL-6619QN2 4.4.0-17134-Microsoft #112-Microsoft Thu Jun 07 22:57:00 PST 2018 x86_64 x86_64 x86_64 GNU/Linux

Exit codes

• 1: on error

2.4 - Namespace src/Aws

src/Aws

Overview

Directory src/Aws

file source src/Aws/imageExists.sh

Aws::imageExists

Checks if image exists with tags provided on AWS ecr best practice: provide tags ’tagPrefix_shortSha’ ’tagPrefix_branchName' so image will be tagged with

• tagPrefix_shortSha
• tagPrefix_branchName

Arguments

• $1 (repositoryName:String): eg:889859566884.dkr.ecr.eu-west-1.amazonaws.com/bast-tools-dev-env
• … (tags:String[]): list of tags used to check if image exists on AWS ECR

Exit codes

• 1: if no tag provided
• 2: if at least one tag does not exist

Output on stderr

• diagnostics information is displayed

Requires

• Aws::requireAwsCommand

src/Aws/requireAwsCommand.sh

file source src/Aws/requireAwsCommand.sh

Aws::requireAwsCommand

ensure command aws is available

Exit codes

• 1: if aws command not available

Output on stderr

• diagnostics information is displayed

2.5 - Namespace src/Backup

src/Backup

Overview

Directory src/Backup

file source src/Backup/dir.sh

Backup::dir

Backup given directory in the base directory or in BACKUP_DIR directory backup directory name is composed by following fields separated by _:

• if BACKUP_DIR is not empty then escaped full dir name separated by @
• date with format %Y%m%d_%H:%M:%S (Eg: 20240326_14:45:08)
• .tgz extension

Arguments

• $1 (string): the base directory
• $2 (string): the directory to backup from base directory

Environment variables

• BACKUP_DIR (String): variable referencing backup directory
• FRAMEWORK_ROOT_DIR (String): used to remove this project directory from displayed backup path
• SUDO (String): allows to use custom sudo prefix command

Exit codes

• 1: if directory to backup does not exist, 0 if everything is OK
• 2: on backup failure

Output on stderr

• message about where the directory is backed up

Requires

• Linux::requireTarCommand

src/Backup/file.sh

file source src/Backup/file.sh

Backup::file

Backup given file in the same directory or in BACKUP_DIR directory backup file name is composed by following fields separated by -:

• if BACKUP_DIR is not empty then escaped dir name separated by @
• filename(without path)
• date with format %Y%m%d_%H:%M:%S (Eg: 20240326_14:45:08)

Arguments

• $1 (file:String): the file to backup

Environment variables

• SUDO (String): allows to use custom sudo prefix command
• BACKUP_DIR (if): not set backup the file in the same directory as original file

Exit codes

• 1: on copy failure

Output on stderr

• messages about backup file location

2.6 - Namespace src/Bash

src/Bash

Overview

Directory src/Bash

file source src/Bash/handlePipelineFailure.sh

Bash::handlePipelineFailure

ignore exit code 141 from simple command pipes

Example

  local resultingStatus=0
  local -a originalPipeStatus=()
  cmd1 | cmd2 || Bash::handlePipelineFailure resultingStatus originalPipeStatus || true
  [[ "${resultingStatus}" = "0" ]]
@arg $1 resultingStatusCode:&int (passed by reference) (optional) resulting status code
@arg $2 originalStatus:int[] (passed by reference) (optional) copy of original PIPESTATUS array
@env PIPESTATUS assuming that this function is called like in the example provided
@see https://unix.stackexchange.com/a/709880/582856
@see https://gitlab.alpinelinux.org/alpine/aports/-/issues/11152
@warning alpine does not support PIPESTATUS very well as execution order of piped process is
not guaranteed

2.7 - Namespace src/Bats

src/Bats

Overview

Directory src/Bats

file source src/Bats/installRequirementsIfNeeded.sh

Bats::installRequirementsIfNeeded

install requirements to execute bats

Environment variables

• BASH_FRAMEWORK_BATS_DEPENDENCIES_CHECK_TIMEOUT (int): default value 86400 (86400 seconds = 1 day)

Variables set

• BASH_FRAMEWORK_BATS_DEPENDENCIES_INSTALLED (String): the file created when all git shallow clones have succeeded

Output on stderr

• diagnostics information is displayed

Features

• Git::shallowClone

Warnings

• the following repositories are shallow cloned
• cloning is skipped if vendor/.batsInstalled file exists
• a new check is done everyday
• repository is not updated if a change is detected

See also

• https://github.com/bats-core/bats-core
• https://github.com/bats-core/bats-support
• https://github.com/bats-core/bats-assert
• https://github.com/Flamefire/bats-mock

2.8 - Namespace src/Cache

src/Cache

Overview

Directory src/Cache

file source src/Cache/getFileContentIfNotExpired.sh

Cache::getFileContentIfNotExpired

get file content if file not expired

Arguments

• $1 (file:String): the file to get content from
• $2 (maxDuration:int): number of seconds after which the file is considered expired

Exit codes

• 1: if file does not exists
• 2: if file expired

Output on stdout

• {String} the file content if not expired

src/Cache/getPropertyValue.sh

file source src/Cache/getPropertyValue.sh

Cache::getPropertyValue

get property value from file if not present compute it using propertyNotFoundCallback (if provided) and store it in property file

Arguments

• $1 (propertyFile:String): the file in which the property will be searched
• $2 (key:String): the property key to search in property file
• $3 (propertyNotFoundCallback:Function): (optional) a callback to call if property key is not found in property file
• … (args:String[]): (optional) the arguments to pass to the propertyNotFoundCallback

Exit codes

• 1: if value is not found
• • if propertyNotFoundCallback fails

Output on stdout

• the property value given by property file or by the propertyNotFoundCallback

src/Cache/getPropertyValue2.sh

file source src/Cache/getPropertyValue2.sh

Cache::getPropertyValue2

get property value from file if not present compute it using propertyNotFoundCallback (if provided) and store it in property file

Arguments

• $1 (propertyFile:String): the file in which the property will be searched
• $2 (key:String): the property key to search in property file
• $3 (propertyNotFoundCallback:Function): (optional) a callback to call if property key is not found in property file
• … (args:String[]): (optional) the arguments to pass to the propertyNotFoundCallback

Exit codes

• 1: if value is not found
• • if propertyNotFoundCallback fails

Output on stdout

• the property value given by property file or by the propertyNotFoundCallback

2.9 - Namespace src/Command

src/Command

Overview

Directory src/Command

file source src/Command/captureOutputAndExitCode.sh

Command::captureOutputAndExitCode

ability to call a command capturing output and exit code but displaying it also to error output to follow command’s progress command output is sent to COMMAND_OUTPUT and stderr as well in realtime using tee

Arguments

• … (command:String[]): the command to execute

Variables set

• COMMAND_OUTPUT (String): stdout of the command is returned in global variable COMMAND_OUTPUT

Exit codes

• • exit code of the command

Output on stderr

• command output

2.10 - Namespace Compiler

2.10.1 - Namespace src/Compiler/Embed

src/Compiler/Embed

Overview

Directory src/Compiler/Embed

file source src/Compiler/Embed/extractDirFromBase64.sh

Compiler::Embed::extractDirFromBase64

convert base64 encoded back to target dir it is advised to include the md5sum of the binFile in the path of the target dir

Arguments

• $1 (targetDir:string): the directory in which tar archive will be untarred
• $2 (base64:string): the base64 encoded tar czf archive

Output on stderr

• diagnostics information is displayed

Requires

• Linux::requireTarCommand

src/Compiler/Embed/extractFileFromBase64.sh

file source src/Compiler/Embed/extractFileFromBase64.sh

Compiler::Embed::extractFileFromBase64

convert base64 encoded back to target file if target file is executable prepend dir of target file to PATH to make binary available everywhere it is advised to include in the path of the target file the md5sum of the binFile

Arguments

• $1 (targetFile:String): the file to write
• $2 (binFileBase64:String): the base64 encoded file
• $3 (fileMode:String): the chmod to set on the file

Variables set

• PATH (String): prepend target embedded file binary directory to PATH variable if binary executable

2.11 - Namespace src/Conf

src/Conf

Overview

Directory src/Conf

file source src/Conf/getAbsoluteFile.sh

Conf::getAbsoluteFile

get absolute conf file from specified conf folder deduced using these rules

• from absolute file (ignores and )
• relative to where script is executed (ignores and )
• from home/.bash-tools/
• from framework conf/

Arguments

• $1 (confFolder:String): the directory name (not the path) to list
• $2 (conf:String): file to use without extension
• $3 (extension:String): the extension (.sh by default)

Exit codes

• 1: if file is not found in any location

Output on stdout

• absolute conf filename

src/Conf/getMergedList.sh

file source src/Conf/getMergedList.sh

Conf::getMergedList

list the conf files list available in bash-tools/conf/ folder and those overridden in ${HOME}/.bash-tools/ folder

Example

- default.local
- default.remote
- localhost-root

Arguments

• $1 (confFolder:String): the directory name (not the path) to list
• $2 (extension:String): the extension (.sh by default)
• $3 (indentStr:String): the indentation (’ - ’ by default) can be any string compatible with sed not containing any /

Output on stdout

• list of files without extension/directory

src/Conf/list.sh

file source src/Conf/list.sh

Conf::list

list files of dir with given extension and display it as a list one by line

Example

      - default.local
      - default.remote
      - localhost-root
@exitcode 1 if directory does not exists

Arguments

• $1 (dir:String): the directory to list
• $2 (prefix:String): the profile file prefix (default: “”)
• $3 (ext:String): the extension
• $4 (findOptions:String): find options, eg: -type d (Default value: ‘-type f’)
• $5 (indentStr:String): the indentation can be any string compatible with sed not containing any / (Default value: ’ - ‘)

Output on stdout

• list of files without extension/directory

src/Conf/load.sh

file source src/Conf/load.sh

Conf::load

get absolute file from name deduced using these rules

• using absolute/relative file (ignores and
• from home/.bash-tools// file
• from framework conf/ file

Arguments

• $1 (confFolder:String): directory to use (traditionally below bash-tools conf folder)
• $2 (conf:String): file to use without extension
• $3 (extension:String): file extension to use (default: .sh)

Exit codes

• 1: if file not found or error during file loading

src/Conf/loadNearestFile.sh

file source src/Conf/loadNearestFile.sh

Conf::loadNearestFile

Load the nearest config file in next example will search first .framework-config file in “srcDir1” then if not found will go in up directories until / then will search in “srcDir2” then if not found will go in up directories until / source the file if found

Example

Conf::loadNearestFile ".framework-config" "srcDir1" "srcDir2"

Arguments

• $1 (configFileName:String): config file name to search
• $2 (loadedFile:String): (passed by reference) will return the loaded config file name
• … (srcDirs:String[]): source directories in which the config file will be searched

Exit codes

• 0: if file found
• 1: if file not found

2.12 - Namespace src/Crypto

src/Crypto

Overview

Directory src/Crypto

file source src/Crypto/uuidV4.sh

Crypto::uuidV4

generate a UUID in version 4 format

Exit codes

• 1: if neither /proc/sys/kernel/random/uuid nor uuidgen are available

Output on stderr

• diagnostics information is displayed

2.13 - Namespace src/Database

src/Database

Overview

Directory src/Database

file source src/Database/checkDsnFile.sh

Database::checkDsnFile

check if dsn file has all the mandatory variables set Mandatory variables are: HOSTNAME, USER, PASSWORD, PORT

Arguments

• $1 (dsnFileName:String): dsn absolute filename

Variables set

• HOSTNAME (loaded): from dsn file
• PORT (loaded): from dsn file
• USER (loaded): from dsn file
• PASSWORD (loaded): from dsn file

Exit codes

• 0: on valid file
• 1: if one of the properties of the conf file is invalid or if file not found

Output on stderr

• log output if error found in conf file

src/Database/createDb.sh

file source src/Database/createDb.sh

Database::createDb

create database if not already existent

Arguments

• $1 (instanceCreateDb:&Map<String,String>): (passed by reference) database instance to use
• $2 (dbName:String): database name to create

Exit codes

• 0: if success
• 1: if query fails

Output on stderr

• display db creation status

src/Database/dropDb.sh

file source src/Database/dropDb.sh

Database::dropDb

drop database if exists

Arguments

• $1 (instanceDropDb:&Map<String,String>): (passed by reference) database instance to use
• $2 (dbName:String): database name to drop

Exit codes

• 0: if success
• 1: query fails

Output on stderr

• display db deletion status

src/Database/dropTable.sh

file source src/Database/dropTable.sh

Database::dropTable

drop table if exists

Arguments

• $1 (instanceDropTable:&Map<String,String>): (passed by reference) database instance to use
• $2 (dbName:String): database name on which the table will be dropped
• $3 (tableName:String): table name to drop

Exit codes

• 0: if success
• 1: if query fails

Output on stderr

• display db table deletion status

src/Database/dump.sh

file source src/Database/dump.sh

Database::dump

dump db limited to optional table list

Arguments

• $1 (instanceDump:&Map<String,String>): (passed by reference) database instance to use
• $2 (db:String): the db to dump
• $3 (optionalTableList:String): (optional) string containing tables list (can be empty string in order to specify additional options)
• $4 (dumpAdditionalOptions:String[]): (optional)_ … additional dump options

Exit codes

• • mysqldump command status code

Output on stderr

• display db sql debug

src/Database/getUserDbList.sh

file source src/Database/getUserDbList.sh

Database::getUserDbList

databases’s list of given mysql server

Example

- information_schema
- mysql
- performance_schema
- sys

Arguments

• $1 (instanceUserDbList:&Map<String,String>): (passed by reference) database instance to use

Exit codes

• • the query exit code

Output on stdout

• the list of db except mysql admin ones (see example)

src/Database/ifDbExists.sh

file source src/Database/ifDbExists.sh

Database::ifDbExists

check if given database exists

Arguments

• $1 (instanceIfDbExists:&Map<String,String>): (passed by reference) database instance to use
• $2 (dbName:String): database name

Exit codes

• 1: if db doesn’t exist

Output on stderr

• debug command

src/Database/isTableExists.sh

file source src/Database/isTableExists.sh

Database::isTableExists

check if table exists on given db

Arguments

• $1 (instanceIsTableExists:&Map<String,String>): (passed by reference) database instance to use
• $2 (dbName:String): database name
• $3 (tableThatShouldExists:String): the table that should exists on this db

Exit codes

• 0: if table exists
• 1: if table doesn’t exist

src/Database/newInstance.sh

file source src/Database/newInstance.sh

Database::newInstance

create a new db instance Returns immediately if the instance is already initialized

Example

declare -Agx dbInstance
Database::newInstance dbInstance "default.local"

Arguments

• $1 (instanceNewInstance:&Map<String,String>): (passed by reference) database instance to use
• $2 (dsn:String): dsn profile - load the dsn.env profile deduced using rules defined in Conf::getAbsoluteFile

Exit codes

• 1: if dns file not able to loaded

src/Database/query.sh

file source src/Database/query.sh

Database::query

mysql query on a given db

Example

  cat file.sql | Database::query ...
@arg $1 instanceQuery:&Map<String,String> (passed by reference) database instance to use
@arg $2 sqlQuery:String (optional) sql query or sql file to execute. if not provided or empty, the command can be piped
@arg $3 dbName:String (optional) the db name

Exit codes

• mysql command status code

Warnings

• could use QUERY_OPTIONS variable from dsn if defined

src/Database/setDumpOptions.sh

file source src/Database/setDumpOptions.sh

Database::setDumpOptions

set the options to use on mysqldump command

Arguments

• $1 (instanceSetDumpOptions:&Map<String,String>): (passed by reference) database instance to use
• $2 (optionsList:String): dump options list

src/Database/setQueryOptions.sh

file source src/Database/setQueryOptions.sh

Database::setQueryOptions

set the general options to use on mysql command to query the database Differs than setOptions in the way that these options could change each time

Arguments

• $1 (instanceSetQueryOptions:&Map<String,String>): (passed by reference) database instance to use
• $2 (optionsList:String): query options list

src/Database/skipColumnNames.sh

file source src/Database/skipColumnNames.sh

Database::skipColumnNames

by default we skip the column names but sometimes we need column names to display some results disable this option temporarily and then restore it to true

Arguments

• $1 (instanceSetQueryOptions:&Map<String,String>): (passed by reference) database instance to use
• $2 (skipColumnNames:Boolean): 0 to disable, 1 to enable (hide column names)

2.14 - Namespace src/Dns

src/Dns

Overview

Directory src/Dns

file source src/Dns/addHost.sh

Dns::addHost

add the line ip hostname at the end of /etc/hosts only if hostname does not exists yet in this file if wsl do the same in ${BASE_MNT_C}/Windows/System32/drivers/etc/hosts

Arguments

• $1 hostName:String
• $2 (ip:String): optional, default value: 127.0.0.1

Environment variables

• BASE_MNT_C (String):
• SUDO (String): allows to use custom sudo prefix command

Output on stderr

• diagnostics information is displayed

Requires

• Git::requireGitCommand
• Linux::requireSudoCommand

Features

• Retry::default

Warnings

• files are backup before being updated

src/Dns/checkHostname.sh

file source src/Dns/checkHostname.sh

Dns::checkHostname

try to ping the dns

Arguments

• $1 (host:String): is the dns hostname

Exit codes

• 1: if host arg empty
• 2: if ping host failed
• 3: if ip is not bound to local ip address
• 4: if ifconfig result is empty

src/Dns/pingHost.sh

file source src/Dns/pingHost.sh

Dns::pingHost

try to ping the given hostname

Arguments

• $1 (host:String): hostname

Exit codes

• 1: if hostname not pinged

Output on stderr

• diagnostics information is displayed

2.15 - Namespace src/Docker

src/Docker

Overview

checkout usage doc below

DockerNamespace usage

file source src/Docker/_.sh

Docker::buildImage

try to docker build image from eventual tagged image cache

• Using DOCKER_BUILDKIT=1
• Using BUILDKIT_INLINE_CACHE in order to use the resulting image as a cache source

You can specify cacheFrom options using the method Docker::getBuildCacheFromArg

Example

## notice that there is no double quotes around $(Docker::getBuildCacheFromArg bash-tools:tag1 bash-tools:tag2)
Docker::buildImage "." "Dockerfile" "bash-tools" $(Docker::getBuildCacheFromArg bash-tools:tag1 bash-tools:tag2)

Arguments

• $1 (buildDirectory:String): base directory from where Dockerfile will take hits resources
• $2 (dockerFilePath:String): docker file path
• $3 (localImageName:String): the local image name of the resulting image (eg: in ubuntu:latest, ubuntu is the image name
• … (dockerBuildParams:String[]): rest of the parameters to pass to docker build method

Exit codes

• 1: if buildDirectory does not exists
• 2: if dockerFilePath does not exists
• 3: if empty or invalid localImageName

Output on stdout

• {String} the tag that has been successfully pulled, return 1 if no

Output on stderr

• diagnostics information is displayed

Requires

• Docker::requireDockerCommand

See also

• https://docs.docker.com/engine/reference/commandline/build/#specifying-external-cache-sources

src/Docker/buildPushDockerImage.sh

file source src/Docker/buildPushDockerImage.sh

Docker::buildPushDockerImage

build image and push it to registry

Environment variables

• DOCKER_OPTION_IMAGE_TAG (String): computed from optionVendor and optionBashVersion if not provided
• DOCKER_OPTION_IMAGE (String): default scrasnups/${DOCKER_OPTION_IMAGE_TAG}
• DOCKER_BUILD_OPTIONS (String): list of docker arguments to pass to docker build command
• FRAMEWORK_ROOT_DIR (String): path allowing to deduce .docker/Dockerfile.{vendor}

src/Docker/getBuildCacheFromArg.sh

file source src/Docker/getBuildCacheFromArg.sh

Docker::getBuildCacheFromArg

generate list of –cache-from arg to pass to docker build

Arguments

• … (tags:String[]): list of tags to use as cache

Output on stdout

• string representing arguments to pass to Docker::buildImage to build image using cache

Requires

• Docker::requireDockerCommand

See also

• Docker::buildImage

src/Docker/getRemoteTag.sh

file source src/Docker/getRemoteTag.sh

Docker::getRemoteTag

generates a string representing a docker remote tag

Example

  id.dkr.ecr.eu-west-1.amazonaws.com/bash-tools:v1.0.0
@arg $1 remoteUrl:String eg: id.dkr.ecr.eu-west-1.amazonaws.com
@arg $2 imageName:String eg: bash-tools
@arg $3 tag:String the tag to retrieve (eg: v1.0.0)
@stdout a string representing a docker remote tag
@require Docker::requireDockerCommand

src/Docker/getTagCompatibleFromBranch.sh

file source src/Docker/getTagCompatibleFromBranch.sh

Docker::getTagCompatibleFromBranch

generates a string compatible with docker tag format Eg: transforms origin/feature/My-beautiful-feature to feature_my_beautiful_feature

Arguments

• $1 (separator:String): replace / by separator (Default value: ‘_’)

Input on stdin

• the name of the branch

Output on stdout

• a string compatible with docker tag format

Requires

• Docker::requireDockerCommand

src/Docker/imageExists.sh

file source src/Docker/imageExists.sh

Docker::imageExists

Check if image is tagged on docker registry best practice: provide tags ’tagPrefix_shortSha’ ’tagPrefix_branchName' so image will be tagged with

• tagPrefix_shortSha
• tagPrefix_branchName

Arguments

• $1 (registryImageUrl:String): eg:889859566884.dkr.ecr.eu-west-1.amazonaws.com/bast-tools-dev-env
• … (tags:String[]): list of tags used to check if image exists on docker registry

Exit codes

• 1: if at least one tag does not exist

Output on stderr

• diagnostics information is displayed

Requires

• Docker::requireDockerCommand

src/Docker/pullImage.sh

file source src/Docker/pullImage.sh

Docker::pullImage

try to docker pull image from pullTags arg best practice: provide tags ’tagPrefix_shortSha’ ’tagPrefix_branchName' so image will be tagged with

• tagPrefix_shortSha
• tagPrefix_branchName

Arguments

• $1 (registryImageUrl:String): eg:889859566884.dkr.ecr.eu-west-1.amazonaws.com/bast-tools-dev-env
• … (tags:String[]): list of tags used to pull image from docker registry

Exit codes

• 1: if tags list is empty or on on invalid argument
• 2: if no image pulled

Output on stdout

• {String} the tag that has been successfully pulled, return 1 if none

Output on stderr

• diagnostics information is displayed

Requires

• Docker::requireDockerCommand

src/Docker/pushImage.sh

file source src/Docker/pushImage.sh

Docker::pushImage

push tagged docker image to docker registry best practice: provide tags ’tagPrefix_shortSha’ ’tagPrefix_branchName' so image will be tagged with

• tagPrefix_shortSha
• tagPrefix_branchName

Arguments

• $1 (registryImageUrl:String): eg:889859566884.dkr.ecr.eu-west-1.amazonaws.com/bast-tools-dev-env
• … (tags:String[]): list of tags used to push image to docker registry

Exit codes

• 1: if tags list is empty

Output on stderr

• diagnostics information is displayed

Requires

• Docker::requireDockerCommand

See also

• Docker::tagImage with the same tags

src/Docker/requireDockerCommand.sh

file source src/Docker/requireDockerCommand.sh

Docker::requireDockerCommand

ensure command docker is available

Exit codes

• 1: if docker command not available

Output on stderr

• diagnostics information is displayed

src/Docker/requireDockerComposeCommand.sh

file source src/Docker/requireDockerComposeCommand.sh

Docker::requireDockerComposeCommand

ensure command docker-compose is available

Exit codes

• 1: if docker-compose command not available

Output on stderr

• diagnostics information is displayed

src/Docker/tagImage.sh

file source src/Docker/tagImage.sh

Docker::tagImage

Image built is tagged with tags provided best practice: provide tags ’tagPrefix_shortSha’ ’tagPrefix_branchName' so image will be tagged with

• tagPrefix_shortSha
• tagPrefix_branchName

Arguments

• $1 (registryImageUrl:String): eg:889859566884.dkr.ecr.eu-west-1.amazonaws.com/bast-tools-dev-env
• $2 (localTag:String): the docker image local tag that needs to be remotely tagged (eg: bash-tools:latest)
• … (tags:String[]): list of tags used to push image to docker registry

Exit codes

• 1: if tags list is empty

Requires

• Docker::requireDockerCommand

src/Docker/testContainer.sh

file source src/Docker/testContainer.sh

Docker::testContainer

Test if a container launched by docker-compose is reachable docker-compose will be up and shutdown at the end of the process if success or not

Arguments

• $1 (dir:String): the directory that contains the docker-compose.yml file
• $2 (containerName:String): name of the container that is tested
• $3 (title:String): a title that allows to discriminate the log lines
• $4 (testCallback:Function): a function callback that will be called to check the container

Exit codes

• 1: if directory does not exists
• 2: on container test failure
• 3: on failure
• 4: if testCallBack is not a function

Requires

• Docker::requireDockerCommand

2.16 - Namespace src/Env

src/Env

Overview

Directory src/Env

file source src/Env/createDefaultEnvFile.sh

Env::createDefaultEnvFile

default env file with all default values

Output on stdout

• the default env filepath

src/Env/pathAppend.sh

file source src/Env/pathAppend.sh

Env::pathAppend

append directories to the PATH environment variable

Arguments

• … (args:String[]): list of directories to append

Variables set

• PATH (String): update PATH with the directories appended

src/Env/pathPrepend.sh

file source src/Env/pathPrepend.sh

Env::pathPrepend

prepend directories to the PATH environment variable

Arguments

• … (args:String[]): list of directories to prepend

Variables set

• PATH (update): PATH with the directories prepended

src/Env/requireLoad.sh

file source src/Env/requireLoad.sh

Env::requireLoad

ensure env files are loaded

Arguments

• … (list): of default files to load at the end

Exit codes

• 1: if one of env files fails to load

Output on stderr

• diagnostics information is displayed

2.17 - Namespace src/File

src/File

Overview

Directory src/File

file source src/File/concatenatePath.sh

File::concatenatePath

concatenate 2 paths and ensure the path is correct using realpath -m

Arguments

• $1 basePath:String
• $2 subPath:String

Requires

• Linux::requireRealpathCommand

src/File/detectBashFile.sh

file source src/File/detectBashFile.sh

File::detectBashFile

check if file provided is a bash file

Arguments

• $@ files:String[]

Variables set

• missingBashFileList (String): temp filepath that contains eventual missing files

Output on stdout

• filepath if Assert::bashFile succeed

See also

• Assert::bashFile

src/File/elapsedTimeSinceLastModification.sh

file source src/File/elapsedTimeSinceLastModification.sh

File::elapsedTimeSinceLastModification

get number of seconds since last modification of the file

Arguments

• $1 (file:String): file path

Exit codes

• 1: if file does not exist

Output on stdout

• number of seconds since last modification of the file

src/File/garbageCollect.sh

file source src/File/garbageCollect.sh

File::garbageCollect

delete files older than n days in given path

Arguments

• $1 (path:String): the directory in which files will be deleted or the file to delete
• $2 (mtime:String): expiration time in days (eg: 1 means 1 day) (default value: 1). Eg: +1 match files that have been accessed at least two days ago (rounding effect)
• $3 (maxdepth:int): Descend at most levels (a non-negative integer) levels of directories below the starting-points. (default value: 1)

Exit codes

• 1: if path not provided or empty
• • find command failure code

Output on stderr

• find output on error or diagnostics logs

Warnings

• use this function with caution as it will delete all files in given path without any prompt

See also

• man find atime

src/File/getAbsolutePath.sh

file source src/File/getAbsolutePath.sh

File::getAbsolutePath

get absolute file from relative path

Arguments

• $1 (file:String): relative file path

Output on stdout

• absolute path (can be $1 if $1 begins with /)

src/File/insertFileAfterToken.sh

file source src/File/insertFileAfterToken.sh

File::insertFileAfterToken

insert file content inside another file after a pattern

Arguments

• $1 (file:String): file in which fileToImport will be
• $2 (fileToImport:String): file to inject before the
• $3 (token:String): token needs to be properly escaped

src/File/insertFileBeforeToken.sh

file source src/File/insertFileBeforeToken.sh

File::insertFileBeforeToken

insert file content inside another file before a pattern

Arguments

• $1 (file:String): file in which fileToImport will be
• $2 (fileToImport:String): file to inject before the
• $3 (token:String): token needs to be properly escaped

src/File/relativeToDir.sh

file source src/File/relativeToDir.sh

File::relativeToDir

print the resolved path relative to DIR do not check for path existence

Arguments

• $1 (srcFile:String): the file to resolve
• $2 (relativeTo:String): the directory

Output on stdout

• the resolved path relative to DIR

src/File/replaceTokenByInput.sh

file source src/File/replaceTokenByInput.sh

File::replaceTokenByInput

replace token by input(stdin) in given targetFile

Arguments

• $1 (token:String): the token to replace by stdin
• $2 (targetFile:String): the file in which token will be replaced by stdin

Exit codes

• 1: if error

Input on stdin

• the file content that will be injected in targetFile

Warnings

• special ansi codes will be removed from stdin

src/File/upFind.sh

file source src/File/upFind.sh

File::upFind

search a file in parent directories

Arguments

• $1 (fromPath:String): path
• $2 fileName:String
• $3 (untilInclusivePath:String): (optional) find for given file until reaching this folder (default value: /)
• … (untilInclusivePaths:String[]): list of untilInclusivePath

Exit codes

• 1: if the command failed or file not found

Output on stdout

• The filename if found

2.18 - Namespace src/Filters

src/Filters

Overview

Directory src/Filters

file source src/Filters/bashFrameworkFunctions.sh

Filters::bashFrameworkFunctions

allows to match a bash framework function based on the naming convention

Arguments

• … (files:String[]): the files in which bash framework functions will be extracted

Environment variables

• PREFIX (String): an eventual prefix you would like to match
• FRAMEWORK_FUNCTIONS_IGNORE_REGEXP (String): this filter does not use this variable

Exit codes

• 0: if match or no match
• 2: if grep fails for other reasons

Input on stdin

• you can alternatively provide content to filter via stdin

Output on stdout

• the list of bash framework function detected

Warnings

• this filter could extract bash framework functions that are actually commented in the source file
• use FRAMEWORK_FUNCTIONS_IGNORE_REGEXP from .framework-config to filter unwanted functions

See also

• bash framework functions naming convention

src/Filters/camel2snakeCase.sh

file source src/Filters/camel2snakeCase.sh

Filters::camel2snakeCase

transform camel case format to snake case

Example

  TEST => test
  camelCase2SnakeCase => camel_case2snake_case
  origin/featureTest/Tools-1456 => origin/feature_test/tools_1456
  # the function is clever enough with some strange case (not really camel case)
  featureTEST/TOOLS-1456 => feature_test/tools_1456
  innovation/vuecli-with-web => innovation/vuecli_with_web
@stdin the string to filter
@stdout the string converted to snake case

src/Filters/commentLines.sh

file source src/Filters/commentLines.sh

Filters::commentLines

remove comment lines from input or files provided as arguments

Arguments

• … (files:String[]): (optional) the files to filter

Environment variables

• commentLinePrefix (String): the comment line prefix (default value: #)

Exit codes

• 0: if lines filtered or not
• 2: if grep fails for any other reasons than not found

Input on stdin

• the file as stdin to filter (alternative to files argument)

Output on stdout

• the filtered lines

src/Filters/firstField.sh

file source src/Filters/firstField.sh

Filters::firstField

equivalent of awk ‘NR==1{print $1}’ allows to retrieve the first field of a piped input

src/Filters/optimizeShFile.sh

file source src/Filters/optimizeShFile.sh

Filters::optimizeShFile

remove shebang line, empty lines and comment lines (just the ones with spaces or not before the # Note: comment after command is more difficult to remove because complicated case could occur Eg: # inside strings like in “sed -E -e ’s/#/…..”

Arguments

• … (files:String[]): the files to filter

Exit codes

• • if one of the filter command fails

Input on stdin

• you can use stdin as alternative to files argument

Output on stdout

• the lines filtered

src/Filters/removeAnsiCodes.sh

file source src/Filters/removeAnsiCodes.sh

Filters::removeAnsiCodes

remove ansi codes from input or files given as argument

Arguments

• … (files:String[]): the files to filter

Exit codes

• • if one of the filter command fails

Input on stdin

• you can use stdin as alternative to files argument

Output on stdout

• the filtered content

See also

• https://en.wikipedia.org/wiki/ANSI_escape_code

src/Filters/removeDuplicatedShebangs.sh

file source src/Filters/removeDuplicatedShebangs.sh

Filters::removeDuplicatedShebangs

remove all shebangs except the first one

Arguments

• … (files:String[]): the files to filter

Exit codes

• • if one of the filter command fails

Input on stdin

• you can use stdin as alternative to files argument

Output on stdout

• the filtered content

src/Filters/removeEmptyLines.sh

file source src/Filters/removeEmptyLines.sh

Filters::removeEmptyLines

remove empty lines and lines containing only spaces

Arguments

• … (files:String[]): the files to filter

Exit codes

• • if one of the filter command fails

Input on stdin

• you can use stdin as alternative to files argument

Output on stdout

• the filtered content

src/Filters/removeEmptyLinesFromBeginning.sh

file source src/Filters/removeEmptyLinesFromBeginning.sh

Filters::removeEmptyLinesFromBeginning

remove empty lines and lines containing only spaces and stops since a non empty line is found

Arguments

• … (files:String[]): the files to filter

Exit codes

• • if one of the filter command fails

Input on stdin

• you can use stdin as alternative to files argument

Output on stdout

• the filtered content

src/Filters/removeExternalQuotes.sh

file source src/Filters/removeExternalQuotes.sh

Filters::removeExternalQuotes

remove quotes (" or ‘) from stdin

Example

  echo '"TEST"' => "TEST"
  echo '"TEST"' | Filters::removeExternalQuotes # => TEST
@arg $@ files:String[] the files to filter
@exitcode * if one of the filter command fails
@stdin you can use stdin as alternative to files argument
@stdout the filtered content

src/Filters/toLowerCase.sh

file source src/Filters/toLowerCase.sh

Filters::toLowerCase

convert text to lower case

Arguments

• $1 (str:String): the string to filter

Exit codes

• • if one of the filter command fails

Input on stdin

• you can use stdin as alternative to str argument

Output on stdout

• the filtered content

src/Filters/toUpperCase.sh

file source src/Filters/toUpperCase.sh

Filters::toUpperCase

convert text to upper case

Arguments

• $1 (str:String): the string to filter

Exit codes

• • if one of the filter command fails

Input on stdin

• you can use stdin as alternative to str argument

Output on stdout

• the filtered content

src/Filters/trimEmptyLines.sh

file source src/Filters/trimEmptyLines.sh

Filters::trimEmptyLines

remove all empty lines

• at the beginning of the file before non empty line
• at the end of the file after last non empty line

Arguments

• … (files:String[]): the files to filter

Exit codes

• • if one of the filter command fails

Input on stdin

• you can use stdin as alternative to files argument

Output on stdout

• the filtered content

See also

• https://unix.stackexchange.com/a/653883

src/Filters/trimString.sh

file source src/Filters/trimString.sh

Filters::trimString

remove leading and trailing spaces of a string

Arguments

• … (files:String[]): the files to filter

Exit codes

• • if one of the filter command fails

Input on stdin

• you can use stdin as alternative to files argument

Output on stdout

• the filtered content

src/Filters/uniqUnsorted.sh

file source src/Filters/uniqUnsorted.sh

Filters::uniqUnsorted

uniq command need input file to be sorted here We are using awk that do not need file to be sorted to get uniq values iterates over each file and prints (default awk behavior) each unique line; only takes first value and ignores duplicates Note ! be careful of memory usage as each unique $0 is stored in an array

Exit codes

• • if one of the filter command fails

Input on stdin

• you can use stdin as alternative to str argument

Output on stdout

• the filtered content

2.19 - Namespace src/Framework

src/Framework

Overview

Directory src/Framework

file source src/Framework/createTempFile.sh

Framework::createTempFile

create a temp file using default TMPDIR variable

Arguments

• $1 (templateName:String): template name to use(optional)

Environment variables

• TMPDIR (String): (default value /tmp)

src/Framework/run.sh

file source src/Framework/run.sh

Framework::run

run command and store data in global variables

• bash_framework_status
• bash_framework_duration
• bash_framework_output redirecting error output to stdout is not supported, you can instead redirect stderr to a file if needed

Arguments

• … (command:String[]): command with arguments to execute

Variables set

• bash_framework_status (the): exit status of the command
• bash_framework_duration (the): duration of the command
• bash_framework_output (the): output of the command

See also

• Command::captureOutputAndExitCode as an alternative

src/Framework/trapAdd.sh

file source src/Framework/trapAdd.sh

Framework::trapAdd

appends a command to a trap when you define a trap, an eventual existing trap is replaced by the new one. This method allows to add trap on several signals without removing previous handler.

Example

trap "echo '- SIGUSR1 original'" SIGUSR1
Framework::trapAdd "echo '- SIGUSR1&2 overridden'" SIGUSR1 SIGUSR2
kill -SIGUSR1 $$
## output
## - SIGUSR1 original
## - SIGUSR1&2 overridden
kill -SIGUSR2 $$
## output
## - SIGUSR1&2 overridden

Arguments

• $1 (trapAddCmd:String): command to execute if trap
• … (signals:String[]): signals to trap

Exit codes

• 1: if traps not provided

See also

• https://stackoverflow.com/a/7287873

2.20 - Namespace src/Git

src/Git

Overview

Directory src/Git

file source src/Git/cloneOrPullIfNoChanges.sh

Git::cloneOrPullIfNoChanges

clone the repository if not done yet, else pull it if no change in it

Arguments

• $1 (dir:String): directory in which repository is installed or will be cloned
• $2 (repo:String): repository url
• $3 (cloneCallback:Function): callback on successful clone
• $4 (pullCallback:Function): callback on successful pull

Environment variables

• GIT_CLONE_OPTIONS:String (additional): options to pass to git clone command
• SUDO (String): allows to use custom sudo prefix command

Exit codes

• 0: on successful pulling/cloning, 1 on failure

src/Git/pullIfNoChanges.sh

file source src/Git/pullIfNoChanges.sh

Git::pullIfNoChanges

pull git directory only if no change has been detected

Arguments

• $1 (dir:String): the git directory to pull

Environment variables

• SUDO (String): allows to use custom sudo prefix command

Exit codes

• 0: on successful pulling
• 1: on any other failure
• 2: changes detected, pull avoided
• 3: not a git directory
• 4: not able to update index
• 5: not a branch, pull avoided

Output on stderr

• diagnostics information is displayed

Requires

• Git::requireGitCommand

src/Git/requireGitCommand.sh

file source src/Git/requireGitCommand.sh

Git::requireGitCommand

ensure command git is available

Exit codes

• 1: if git command not available

Output on stderr

• diagnostics information is displayed

src/Git/shallowClone.sh

file source src/Git/shallowClone.sh

Git::shallowClone

shallow clone a repository at specific commit sha, tag or branch or update repo if already exists

Arguments

• $1 repository:String
• $2 (installDir:String): Install dir
• $3 (revision:String): commit sha, tag or branch
• $4 (forceDeletion:Boolean): (optional) put “FORCE_DELETION” to force directory deletion if directory exists and it’s not a git repository (default: 0)

Exit codes

• !=0: if git failure or directory not writable
• 1: if destination dir already exists and force option is not 1

Output on stderr

• display verbose status of the command execution

Warnings

• USE THIS FORCE_DELETION ARGUMENT WITH CAUTION !!! as the directory will be deleted without any prompt

2.21 - Namespace src/Github

src/Github

Overview

Directory src/Github

file source src/Github/defaultInstall.sh

Github::downloadReleaseVersion

download specified release software version from github

Arguments

• $1 (releaseUrl:String): eg: https://github.com/kubernetes-sigs/kind/releases/download/v1.0.0/kind-linux-amd64

Environment variables

• CURL_CONNECT_TIMEOUT (number): of seconds before giving up host connection

Exit codes

• 1: on failure

Output on stdout

• the path to the downloaded release

src/Github/extractRepoFromGithubUrl.sh

file source src/Github/extractRepoFromGithubUrl.sh

Github::extractRepoFromGithubUrl

github repository eg: kubernetes-sigs/kind

Arguments

• $1 (githubUrl:String): eg: https://github.com/kubernetes-sigs/kind/releases/download/@latestVersion@/kind-linux-amd64

Exit codes

• 1: if no matching repo found in provided url, 0 otherwise

Output on stdout

• the repo in the form owner/repo

src/Github/getLatestRelease.sh

file source src/Github/getLatestRelease.sh

Github::getLatestRelease

Retrieve the latest version number of a github release using Github API using retry repo arg with fchastanet/bash-tools value would match https://github.com/fchastanet/bash-tools

Arguments

• $1 (repo:String): repository in the format fchastanet/bash-tools
• $2 (resultRef:&String): reference to a variable that will contain the result of the command

Environment variables

• CURL_CONNECT_TIMEOUT (number): of seconds before giving up host connection

Output on stdout

• log messages about retry

src/Github/getLatestVersionFromUrl.sh

file source src/Github/getLatestVersionFromUrl.sh

Github::getLatestVersionFromUrl

Retrieve the latest version number for given github url

Arguments

• $1 (releaseUrl:String): github url from which repository will be extracted

Output on stdout

• the version number retrieved

Output on stderr

• log messages about retry

src/Github/installRelease.sh

file source src/Github/installRelease.sh

Github::installRelease

install binary with the exact version provided using retry

releaseUrl argument: the placeholder @latestVersion@ will be replaced by the provided version

Arguments

• $1 (targetFile:String): target binary file (eg: /usr/local/bin/kind)
• $2 (releaseUrl:String): github release url (eg: https://github.com/kubernetes-sigs/kind/releases/download/@latestVersion@/kind-linux-amd64)
• $3 (exactVersion:String): which exact version to get
• $4 (argVersion:String): the argument used to get the version of the command (default: –version)
• $5 (versionCallback:Function): called to get software version (default: Version::getCommandVersionFromPlainText will call software with argument –version)
• $6 (installCallback:Function): called to install the file retrieved on github (default copy as is and set execution bit)

Environment variables

• CURL_CONNECT_TIMEOUT (number): of seconds before giving up host connection
• VERSION_PLACEHOLDER (a): placeholder to replace in downloadReleaseUrl (default: @latestVersion@)

Output on stdout

• log messages about retry, install, upgrade

src/Github/isReleaseVersionExist.sh

file source src/Github/isReleaseVersionExist.sh

Github::isReleaseVersionExist

check if specified release software version exists in github

Arguments

• $1 (releaseUrl:String): eg: https://github.com/kubernetes-sigs/kind/releases/download/v1.0.0/kind-linux-amd64

Environment variables

• CURL_CONNECT_TIMEOUT (number): of seconds before giving up host connection

Exit codes

• 1: on failure
• 0: if release version exists

src/Github/upgradeRelease.sh

file source src/Github/upgradeRelease.sh

Github::upgradeRelease

upgrade given binary to latest github release using retry

downloadReleaseUrl argument : the placeholder @latestVersion@ will be replaced by the latest release version

Arguments

• $1 (targetFile:String): target binary file (eg: /usr/local/bin/kind)
• $2 (downloadReleaseUrl:String): github release url (eg: https://github.com/kubernetes-sigs/kind/releases/download/@latestVersion@/kind-linux-amd64)
• $3 (softVersionArg:String): parameter to add to existing command to compute current version
• $4 (softVersionCallback:Function): function called to get software version (default: Version::getCommandVersionFromPlainText will call software with argument –version)
• $5 (installCallback:Function): function called to install the file retrieved on github (default copy as is and set execution bit)
• $6 (softVersionCallback:Function): function to call to filter the version retrieved from github (Default: Version::parse)

Environment variables

• SOFT_VERSION_CALLBACK (pass): softVersionCallback by env variable instead of passing it by arg
• INSTALL_CALLBACK (pass): installCallback by env variable instead of passing it by arg
• CURL_CONNECT_TIMEOUT (number): of seconds before giving up host connection
• EXACT_VERSION (if): provided, retrieve exact version instead of the latest

Output on stdout

• log messages about retry, install, upgrade

2.22 - Namespace src/Install

src/Install

Overview

Directory src/Install

file source src/Install/dir.sh

Install::dir

install dir to given directory but backup it before

Arguments

• $1 (fromDir:String): the source base directory
• $2 (toDir:String): the target base directory
• $3 (dirName:String): the directory relative to fromDir arg that will be copied
• $4 (userName:String): (optional) (default: ${USERNAME}) the user name that will be used to set target files ownership
• $5 (userGroup:String): (optional) (default: ${USERNAME}) the group name that will be used to set target files ownership

Environment variables

• OVERWRITE_CONFIG_FILES (Boolean): (default:0) if 1 will overwrite existing directory
• CHANGE_WINDOWS_FILES (Boolean): (default:0) if 1 and target directory is in windows file system, overwrite it
• USERNAME ((default:): root) the user name that will be used to set target files ownership
• USERGROUP ((default:): root) the group name that will be used to set target files ownership
• BASE_MNT_C (String): windows C drive base PATH
• FRAMEWORK_ROOT_DIR (used): to make paths relative to this directory to reduce length of messages
• SUDO (String): allows to use custom sudo prefix command
• BACKUP_BEFORE_INSTALL (Boolean): (default:1) backup directory before installing the dir

Exit codes

• 1: if source directory is not readable
• 2: if source directory backup failed
• 0: if copy successful or OVERWRITE_CONFIG_FILES=0 or
• 0: with warning message if OVERWRITE_CONFIG_FILES=0 and target directory exists
• 0: with warning message if CHANGE_WINDOWS_FILES=0 and target directory in C drive

Output on stderr

• diagnostics information is displayed, skipped information if OVERWRITE_CONFIG_FILES or CHANGE_WINDOWS_FILES are set to 1

src/Install/file.sh

file source src/Install/file.sh

Install::file

installs file to given directory

callbacks parameters ${fromFile} ${targetFile} $@

Arguments

• $1 (fromFile): - original file to copy
• $2 (targetFile): - target file
• $3 (userName:String): (optional) (default: ${USERNAME}) the user name that will be used to set target files ownership
• $4 (userGroup:String): (optional) (default: ${USERNAME}) the group name that will be used to set target files ownership
• $5 (successCallback:Function): the callback to call when file is installed successfully, by default setUserRights callback is called
• $6 (failureCallback:Function): the callback to call when file installation has failed, by default unableToCopyCallback callback is called
• … (callbacksParams:String[]): additional parameters passed to callbacks

Environment variables

• OVERWRITE_CONFIG_FILES (Boolean): (default:0) if 1 will overwrite existing directory
• CHANGE_WINDOWS_FILES (Boolean): (default:0) if 1 and target file is in windows file system, overwrite it
• USERNAME ((default:): root) the user name that will be used to set target files ownership
• USERGROUP ((default:): root) the group name that will be used to set target files ownership
• BASE_MNT_C (String): windows C drive base PATH
• FRAMEWORK_ROOT_DIR (used): to make paths relative to this directory to reduce length of messages
• SUDO (String): allows to use custom sudo prefix command
• BACKUP_BEFORE_INSTALL (Boolean): (default: 1) backup file before installing the file

Exit codes

• 1: if fromFile is not readable
• 2: if backup file failure
• 3: if copy failure
• 0: on success or if OVERWRITE_CONFIG_FILES=0
• 0: on success or if CHANGE_WINDOWS_FILES=0 and target file is a windows file

src/Install/setRootExecutableCallback.sh

file source src/Install/setRootExecutableCallback.sh

Install::setRootExecutableCallback

install callback set file with root ownership and execution bit

Arguments

• $1 fromFile:String
• $2 targetFile:String

Environment variables

• SUDO (String): allows to use custom sudo prefix command

Exit codes

• 1: on any failure

See also

• Install::file

src/Install/setUserRightsCallback.sh

file source src/Install/setUserRightsCallback.sh

Install::setUserRightsCallback

install callback set file with root ownership and execution bit

Arguments

• $1 fromFile:String
• $2 targetFile:String
• $3 (userName:String): (optional) (default: ${USERNAME}) the user name that will be used to set target files ownership
• $4 (userGroup:String): (optional) (default: ${USERNAME}) the group name that will be used to set target files ownership

Environment variables

• USERNAME ((default:): root) the user name that will be used to set target files ownership
• USERGROUP ((default:): root) the group name that will be used to set target files ownership
• SUDO (String): allows to use custom sudo prefix command

Exit codes

• 1: on any failure

See also

• Install::file

src/Install/setUserRootCallback.sh

file source src/Install/setUserRootCallback.sh

Install::setUserRootCallback

install callback set file with root ownership

Arguments

• $1 fromFile:String
• $2 targetFile:String

Environment variables

• SUDO (String): allows to use custom sudo prefix command

Exit codes

• 1: on any failure

See also

• Install::file

src/Install/structure.sh

file source src/Install/structure.sh

Install::structure

install dir to given directory but backup it before

Arguments

• $1 (fromDir:String): the source base directory
• $2 (toDir:String): the target base directory

Environment variables

• OVERWRITE_CONFIG_FILES (Boolean): (default:0) if 1 will overwrite existing files
• CHANGE_WINDOWS_FILES (Boolean): (default:0) if 1 and target directory is in windows file system, overwrite it
• USERNAME ((default:): ${USERNAME} if SUDO empty else root) the user name that will be used to set target files ownership
• USERGROUP ((default:): ${USERGROUP} if SUDO empty else root) the group name that will be used to set target files ownership
• BASE_MNT_C (String): windows C drive base PATH
• PRETTY_ROOT_DIR (used): to make paths relative to this directory to reduce length of messages
• SUDO (String): allows to use custom sudo prefix command
• BACKUP_BEFORE_INSTALL (Boolean): (default:1) backup directory before installing the dir

Exit codes

• 1: if source directory is not readable
• 2: if error during structure replication
• 2: if error during file copy
• 0: if copy successful
• 0: with warning message if CHANGE_WINDOWS_FILES=0 and target directory in C drive

Output on stderr

• diagnostics information is displayed, skipped information if OVERWRITE_CONFIG_FILES or CHANGE_WINDOWS_FILES are set to 1

src/Install/unableToCopyCallback.sh

file source src/Install/unableToCopyCallback.sh

Install::unableToCopyCallback

install callback default callback used called when file copy has failed

Arguments

• $1 fromFile:String
• $2 targetFile:String

Environment variables

• FRAMEWORK_ROOT_DIR (used): to make paths relative to this directory to reduce length of messages

Exit codes

• 1: always fail

Output on stderr

• diagnostics information is displayed

See also

• Install::file

2.23 - Namespace Linux

2.23.1 - Namespace src/Linux/Apt

src/Linux/Apt

Overview

Directory src/Linux/Apt

file source src/Linux/Apt/addRepository.sh

Linux::Apt::addRepository

add apt repository followed by an apt-get update

Environment variables

• SKIP_APT_GET_UPDATE

Output on stdout

• diagnostics logs

Requires

• Linux::requireUbuntu

Features

• Retry::default

src/Linux/Apt/install.sh

file source src/Linux/Apt/install.sh

Linux::Apt::install

apt-get install

Arguments

• … (softwares:String[]): list of softwares to install

Output on stdout

• diagnostics logs

Requires

• Linux::requireUbuntu

Features

• Retry::default

src/Linux/Apt/installIfNecessary.sh

file source src/Linux/Apt/installIfNecessary.sh

Linux::Apt::installIfNecessary

apt-get install if package is not installed yet

Arguments

• … (packages:String[]): list of packages to install

Environment variables

• SKIP_APT_GET_UPDATE

Output on stdout

• diagnostics logs

Requires

• Linux::requireUbuntu

Features

• Retry::default

src/Linux/Apt/isPackageInstalled.sh

file source src/Linux/Apt/isPackageInstalled.sh

Linux::Apt::isPackageInstalled

check if apt package is installed

Arguments

• $1 (package:String): the package name to check

Output on stdout

• diagnostics logs

Requires

• Linux::requireUbuntu

src/Linux/Apt/remove.sh

file source src/Linux/Apt/remove.sh

Linux::Apt::remove

remove ubuntu packages

Arguments

• … (softwares:String[]): list of softwares to remove

Output on stdout

• diagnostics logs

Requires

• Linux::requireUbuntu

Features

• Retry::default

src/Linux/Apt/repositoryExists.sh

file source src/Linux/Apt/repositoryExists.sh

Linux::Apt::repositoryExists

check if apt repository is added to apt sources Linux::requireSudoCommand

Output on stdout

• diagnostics logs

Requires

• Linux::requireUbuntu

src/Linux/Apt/update.sh

file source src/Linux/Apt/update.sh

Linux::Apt::update

update apt packages list

Output on stdout

• diagnostics logs

Requires

• Linux::requireUbuntu

Features

• Retry::default

2.23.2 - Namespace src/Linux/Sudo

src/Linux/Sudo

Overview

Directory src/Linux/Sudo

file source src/Linux/Sudo/asUser.sh

Linux::Sudo::asUser

execute command passed as arguments using sudo if current user is not already the targeted user

Arguments

• … (args:String[]): the command to execute as sudo

Environment variables

• USERNAME (String): sudo as this user (root by default)

Exit codes

• 1: exit code of command

Requires

• Linux::requireSudoCommand

src/Linux/Sudo/asUserInheritEnv.sh

file source src/Linux/Sudo/asUserInheritEnv.sh

Linux::Sudo::asUserInheritEnv

execute command passed as arguments using sudo with environment inherited if current user is not already the targeted user

Arguments

• … (args:String[]): the command to execute as sudo

Environment variables

• USERNAME (String): sudo as this user (root by default)

Exit codes

• 1: exit code of sudo command

Requires

• Linux::requireSudoCommand

2.23.3 - Namespace src/Linux/Wsl

src/Linux/Wsl

Overview

Directory src/Linux/Wsl

file source src/Linux/Wsl/assertWindowsEtcHost.sh

Linux::Wsl::assertWindowsEtcHost

Check if Host is defined in etc/hosts of windows

Arguments

• $1 host:String

Exit codes

• 1: if hostname not found

src/Linux/Wsl/cachedWslpath.sh

file source src/Linux/Wsl/cachedWslpath.sh

Linux::Wsl::cachedWslpath

retrieve wslpath using cache (cache is refreshed every day)

Arguments

• … (args:String[]): arguments to pass to wslpath

Environment variables

• WSL_TMPDIR (String): temp directory to store the wslpath cache (default value: TMPDIR), you can use PERSISTENT_TMPDIR instead

Exit codes

• • if Linux::Wsl::originalWslpath cannot find the path

Output on stderr

• diagnostics information is displayed

Requires

• Linux::Wsl::requireWsl

Features

• cache

src/Linux/Wsl/cachedWslpath2.sh

file source src/Linux/Wsl/cachedWslpath2.sh

Linux::Wsl::cachedWslpath2

retrieve wslpath using cache (cache is refreshed every day)

Arguments

• … (args:String[]): arguments to pass to wslpath

Environment variables

• WSL_TMPDIR (String): temp directory to store the wslpath cache (default value: PERSISTENT_TMPDIR), you can use TMPDIR instead

Exit codes

• • if Linux::Wsl::originalWslpath cannot find the path

Output on stderr

• diagnostics information is displayed

Requires

• Linux::Wsl::requireWsl

Features

• cache

src/Linux/Wsl/cachedWslpathFromWslVar.sh

file source src/Linux/Wsl/cachedWslpathFromWslVar.sh

Linux::Wsl::cachedWslpathFromWslVar

retrieve path from wslvar and then use wslpath to resolve it using cache (cache is refreshed every day)

Arguments

• $1 (var:String): the var to retrieve using wslvar
• … (args:String[]): (optional) additional arguments to pass to wslvar

Environment variables

• WSL_TMPDIR (String): temp directory to store the wslpath cache (default value: TMPDIR), you can use PERSISTENT_TMPDIR instead

Exit codes

• • if Linux::Wsl::originalWslpath cannot find the path or Linux::Wsl::originalWslvar cannot find the var

Output on stderr

• diagnostics information is displayed

Requires

• Linux::Wsl::requireWsl

Features

• cache

src/Linux/Wsl/cachedWslpathFromWslVar2.sh

file source src/Linux/Wsl/cachedWslpathFromWslVar2.sh

Linux::Wsl::cachedWslpathFromWslVar2

retrieve path from wslvar and then use wslpath to resolve it using cache (cache is refreshed every day)

Arguments

• $1 (var:String): the var to retrieve using wslvar
• … (args:String[]): (optional) additional arguments to pass to wslvar

Environment variables

• WSL_TMPDIR (String): temp directory to store the wslpath cache (default value: PERSISTENT_TMPDIR), you can use TMPDIR instead

Exit codes

• 1: if var cannot be found in cache nor using Linux::Wsl::originalWslvar
• 2: if path cannot be found in cache nor using Linux::Wsl::originalWslpath

Output on stderr

• diagnostics information is displayed

Requires

• Linux::Wsl::requireWsl

Features

• cache

src/Linux/Wsl/cachedWslvar.sh

file source src/Linux/Wsl/cachedWslvar.sh

Linux::Wsl::cachedWslvar

retrieve wslvar using cache (cache is refreshed every day)

Arguments

• … (args:String[]): arguments to pass to wslvar

Environment variables

• WSL_TMPDIR (String): temp directory to store the wslvar cache (default value: TMPDIR), you can use PERSISTENT_TMPDIR instead

Exit codes

• • if Linux::Wsl::originalWslvar cannot find the variable

Output on stderr

• diagnostics information is displayed

Requires

• Linux::Wsl::requireWsl

Features

• cache

src/Linux/Wsl/cachedWslvar2.sh

file source src/Linux/Wsl/cachedWslvar2.sh

Linux::Wsl::cachedWslvar2

retrieve wslvar using cache (cache is refreshed every day)

Arguments

• $1 (cachedWslvar2_var:&String): the variable to set by reference if the value is found
• … (args:String[]): arguments to pass to wslvar

Environment variables

• WSL_TMPDIR (String): temp directory to store the wslvar cache (default value: PERSISTENT_TMPDIR), you can use TMPDIR instead

Exit codes

• • if Linux::Wsl::originalWslvar cannot find the variable

Output on stderr

• diagnostics information is displayed

Requires

• Linux::Wsl::requireWsl

Features

• cache

src/Linux/Wsl/initEnv.sh

file source src/Linux/Wsl/getKeyFromWslpathOptions.sh

Linux::Wsl::initEnv

initialize some important variables for scripts to run correctly when wsl installation is run under wsl is in progress

Function has no arguments.

Environment variables

• WSL_INIT (int): 0 to disable wsl env initialization

Variables set

• PATH (String): populated with WINDOW_PATH paths
• WSL_INTEROP (String): with current used process
• WSL_DISTRO_NAME (String): initialized using wslpath -m /

Output on stderr

• diagnostics information is displayed

Requires

• Linux::Wsl::requireWsl

Features

• cache

Warnings

• initialization skipped if script not run under wsl

src/Linux/Wsl/originalWslpath.sh

file source src/Linux/Wsl/originalWslpath.sh

Linux::Wsl::originalWslpath

call simply original wslpath command

Arguments

• … (args:String[]): args to pass to wslpath

Exit codes

• • wslpath exit code

Output on stdout

• wslpath stdout

Requires

• Linux::Wsl::requireWsl

src/Linux/Wsl/originalWslvar.sh

file source src/Linux/Wsl/originalWslvar.sh

Linux::Wsl::originalWslvar

call simply original wslvar command

Arguments

• … (args:String[]): args to pass to wslvar

Exit codes

• • wslvar exit code

Output on stdout

• wslvar stdout

Requires

• Linux::Wsl::requireWsl

src/Linux/Wsl/requireWsl.sh

file source src/Linux/Wsl/requireWsl.sh

Linux::Wsl::requireWsl

ensure linux runs under wsl

Environment variables

• WSL_GARBAGE_COLLECT (int): 0 to disable garbage collect of cache files

Exit codes

• 1: if linux does not run under wsl

2.24 - Namespace src/Log

src/Log

Overview

Log namespace provides 2 kind of functions

• Log::display* allows to display given message with given display level
• Log::log* allows to log given message with given log level Log::display* functions automatically log the message too

file source src/Log/_.sh

Log::computeDuration

compute duration since last call to this function the result is set in following env variables. in ss.sss (seconds followed by milliseconds precision 3 decimals)

Function has no arguments.

Environment variables

• DISPLAY_DURATION (int): (default 0) if 1 display elapsed time information between 2 info logs

Variables set

• LOG_LAST_LOG_DATE_INIT (int): (default 1) set to 0 at first call, allows to detect reference log
• LOG_LAST_DURATION_STR (String): the last duration displayed
• LOG_LAST_LOG_DATE (String): the last log date that will be used to compute next diff

src/Log/displayDebug.sh

file source src/Log/displayDebug.sh

Log::displayDebug

Display message using debug color (gray)

Arguments

• $1 (message:String): the message to display

Environment variables

• DISPLAY_DURATION (int): (default 0) if 1 display elapsed time information between 2 info logs
• LOG_CONTEXT (String): allows to contextualize the log

src/Log/displayError.sh

file source src/Log/displayError.sh

Log::displayError

Display message using error color (red)

Arguments

• $1 (message:String): the message to display

Environment variables

• DISPLAY_DURATION (int): (default 0) if 1 display elapsed time information between 2 info logs
• LOG_CONTEXT (String): allows to contextualize the log

src/Log/displayHelp.sh

file source src/Log/displayHelp.sh

Log::displayHelp

Display message using info color (bg light blue/fg white)

Arguments

• $1 (message:String): the message to display

Environment variables

• DISPLAY_DURATION (int): (default 0) if 1 display elapsed time information between 2 info logs
• LOG_CONTEXT (String): allows to contextualize the log

src/Log/displayInfo.sh

file source src/Log/displayInfo.sh

Log::displayInfo

Display message using info color (bg light blue/fg white)

Arguments

• $1 (message:String): the message to display

Environment variables

• DISPLAY_DURATION (int): (default 0) if 1 display elapsed time information between 2 info logs
• LOG_CONTEXT (String): allows to contextualize the log

src/Log/displaySkipped.sh

file source src/Log/displaySkipped.sh

Log::displaySkipped

Display message using skip color (yellow)

Arguments

• $1 (message:String): the message to display

Environment variables

• DISPLAY_DURATION (int): (default 0) if 1 display elapsed time information between 2 info logs
• LOG_CONTEXT (String): allows to contextualize the log

src/Log/displayStatus.sh

file source src/Log/displayStatus.sh

Log::displayStatus

Display message using info color (blue) but warning level

Arguments

• $1 (message:String): the message to display

Environment variables

• DISPLAY_DURATION (int): (default 0) if 1 display elapsed time information between 2 info logs
• LOG_CONTEXT (String): allows to contextualize the log

src/Log/displaySuccess.sh

file source src/Log/displaySuccess.sh

Log::displaySuccess

Display message using success color (bg green/fg white)

Arguments

• $1 (message:String): the message to display

Environment variables

• DISPLAY_DURATION (int): (default 0) if 1 display elapsed time information between 2 info logs
• LOG_CONTEXT (String): allows to contextualize the log

src/Log/displayWarning.sh

file source src/Log/displayWarning.sh

Log::displayWarning

Display message using warning color (yellow)

Arguments

• $1 (message:String): the message to display

Environment variables

• DISPLAY_DURATION (int): (default 0) if 1 display elapsed time information between 2 info logs
• LOG_CONTEXT (String): allows to contextualize the log

src/Log/fatal.sh

file source src/Log/fatal.sh

Log::fatal

Display message using error color (red) and exit immediately with error status 1

Arguments

• $1 (message:String): the message to display

Environment variables

• DISPLAY_DURATION (int): (default 0) if 1 display elapsed time information between 2 info logs
• LOG_CONTEXT (String): allows to contextualize the log

src/Log/getLevelText.sh

file source src/Log/getLevelText.sh

Log::getLevelText

Get the text representation of a log level

Arguments

• $1 (level:String): the log level to convert

Exit codes

• 1: if the level is invalid

src/Log/logDebug.sh

file source src/Log/logDebug.sh

Log::logDebug

log message to file

Arguments

• $1 (message:String): the message to display

src/Log/logError.sh

file source src/Log/logError.sh

Log::logError

log message to file

Arguments

• $1 (message:String): the message to display

src/Log/logFatal.sh

file source src/Log/logFatal.sh

Log::logFatal

log message to file

Arguments

• $1 (message:String): the message to display

src/Log/logHelp.sh

file source src/Log/logHelp.sh

Log::logHelp

log message to file

Arguments

• $1 (message:String): the message to display

src/Log/logInfo.sh

file source src/Log/logInfo.sh

Log::logInfo

log message to file

Arguments

• $1 (message:String): the message to display

src/Log/logMessage.sh

file source src/Log/logMessage.sh

Log::logMessage

Internal: common log message

Example

[date]|[levelMsg]|message
2020-01-19 19:20:21|ERROR  |log error
2020-01-19 19:20:21|SKIPPED|log skipped

Arguments

• $1 (levelMsg:String): message’s level description (eg: STATUS, ERROR, …)
• $2 (msg:String): the message to display

Environment variables

• BASH_FRAMEWORK_LOG_FILE (String): log file to use, do nothing if empty
• BASH_FRAMEWORK_LOG_LEVEL (int): log level log only if > OFF or fatal messages

Output on stderr

• diagnostics information is displayed

Requires

• Env::requireLoad
• Log::requireLoad

src/Log/logSkipped.sh

file source src/Log/logSkipped.sh

Log::logSkipped

log message to file

Arguments

• $1 (message:String): the message to display

src/Log/logStatus.sh

file source src/Log/logStatus.sh

Log::logStatus

log message to file

Arguments

• $1 (message:String): the message to display

src/Log/logSuccess.sh

file source src/Log/logSuccess.sh

Log::logSuccess

log message to file

Arguments

• $1 (message:String): the message to display

src/Log/logWarning.sh

file source src/Log/logWarning.sh

Log::logWarning

log message to file

Arguments

• $1 (message:String): the message to display

src/Log/requireLoad.sh

file source src/Log/requireLoad.sh

Log::requireLoad

activate or not Log::display* and Log::log* functions based on BASH_FRAMEWORK_DISPLAY_LEVEL and BASH_FRAMEWORK_LOG_LEVEL environment variables loaded by Env::requireLoad try to create log file and rotate it if necessary

Function has no arguments.

Environment variables

• BASH_FRAMEWORK_DISPLAY_LEVEL (int):
• BASH_FRAMEWORK_LOG_LEVEL (int):
• BASH_FRAMEWORK_LOG_FILE (String):
• BASH_FRAMEWORK_LOG_FILE_MAX_ROTATION (int): do log rotation if > 0

Variables set

• BASH_FRAMEWORK_LOG_LEVEL (int): to OFF level if BASH_FRAMEWORK_LOG_FILE is empty or not writable

Exit codes

• 0: always successful

Output on stderr

• diagnostics information about log file is displayed

Requires

• Env::requireLoad
• UI::requireTheme

src/Log/rotate.sh

file source src/Log/rotate.sh

Log::rotate

To be called before logging in the log file

Arguments

• $1 (file:string): log file name
• $2 (maxLogFilesCount:int): maximum number of log files

2.25 - Namespace src/Profiles

src/Profiles

Overview

Directory src/Profiles

file source src/Profiles/allDepsRecursive.sh

Profiles::allDepsRecursive

get recursively all the dependencies of each config from configs arg

The parent argument must be set to “your software selection” when you call it, then the value will change when this function will be called recursively with the parent dependency

Algorithm For each config in configs - load config definition - mark this config as seen to avoid to recompute it later, in the case where another definition depends on it - call installScripts_${config}_dependencies function if exists (skipped if not) - add these new dependencies if any to current dependencies list - call recursively Profiles::allDepsRecursive with these dependencies - add in allDepsResult the current config if it was not seen yet This has constructed a tree with the most deep dependency present in the first items

Arguments

• $1 (scriptsDir:String): base directory where dependencies can be retrieved
• $2 (parent:String): set to “your software selection” when you call it
• … (configs:String[]): list of configurations to load, each config can depend on an other one

Variables set

• allDepsResultSeen (String[]): list of dependencies already seen
• allDepsResult (String[]): the final list of dependencies sorted by the most to less dependent

Exit codes

• 1: if one of the dependency cannot be found
• 2: if error while loading one of the dependency definition
• 3: if error while calling dependencies function of the dependency’s definition

Output on stderr

• diagnostics information is displayed

Warnings

• allDepsResultSeen and allDepsResult global variables have to reset to empty array every time you call this function

src/Profiles/checkScriptsExistence.sh

file source src/Profiles/checkScriptsExistence.sh

Profiles::checkScriptsExistence

check if dependencies exist path is constructed with following rule ${scriptsDir}/${dependency}${extension}

Arguments

• $1 scriptsDir:String
• $2 extension:String
• … (args:String[]): list of dependencies to check

Exit codes

• 1: if one the script does not exist

Output on stderr

• diagnostics information is displayed

src/Profiles/lintDefinitions.sh

file source src/Profiles/lintDefinitions.sh

Profiles::lintDefinitions

linter that allows to check if a list of methods is defined in each sh file of given scriptsDir

Arguments

• $1 (scriptsDir:String): the directory to check
• $2 (format:String): can be plain or checkstyle
• $@ args:String[]

Exit codes

• 1: if errorCount > 0

Output on stderr

• diagnostics information is displayed

2.26 - Namespace src/Retry

src/Retry

Overview

Directory src/Retry

file source src/Retry/default.sh

Retry::default

Retry a command 5 times with a delay of 15 seconds between each attempt

Arguments

• … (command:String[]): the command to run

Environment variables

• RETRY_MAX_RETRY (int): max retries
• RETRY_DELAY_BETWEEN_RETRIES (int): delay between attempts

Exit codes

• 0: on success
• 1: if max retries count reached

src/Retry/parameterized.sh

file source src/Retry/parameterized.sh

Retry::parameterized

Retry a command several times depending on parameters

Arguments

• $1 (maxRetries:int): $1 max retries
• $2 (delay:int): between attempt
• $3 (message:String): to display to describe the attempt
• … (rest): of parameters, the command to run

Exit codes

• 0: on success
• 1: if max retries count reached
• 2: if maxRetries invalid value

2.27 - Namespace src/ShellDoc

src/ShellDoc

Overview

Directory src/ShellDoc

file source src/ShellDoc/fixMarkdownToc.sh

ShellDoc::fixMarkdownToc

fix markdown TOC generated by Markdown all in one vscode extension to make TOC compatible with docsify

Arguments

• $1 (file:String): file to fix

Exit codes

• 1: if awk fails

See also

• https://regex101.com/r/DJJf2I/1

src/ShellDoc/generateMdFileFromTemplate.sh

file source src/ShellDoc/generateMdFileFromTemplate.sh

ShellDoc::generateMdFileFromTemplate

generates markdown file from template by replacing @@@command_help@@@ by the help of the command eg: @@@test_help@@@ will be replaced by the output of the command test --help in the directory provided

Arguments

• $1 (templateFile:String): the file to use as template
• $2 (targetFile:String): the target file
• $3 (fromDir:String): the directory from which commands will be searched
• $4 (tokenNotFoundCount:&int): (passed by reference) number of tokens @@@command_help@@@ not found in the template file
• $5 (excludeFilesPattern:String): grep exclude pattern (eg: ‘^(compile)$’) (default value: “”)

Output on stdout

• the generated markdown with help of the matching command

Output on stderr

• diagnostics logs

src/ShellDoc/generateShellDoc.sh

file source src/ShellDoc/generateShellDoc.sh

ShellDoc::generateShellDoc

extract shDoc from file

Arguments

• $1 file:String

Output on stdout

• the shell documentation in markdown format

src/ShellDoc/generateShellDocDir.sh

file source src/ShellDoc/generateShellDocDir.sh

ShellDoc::generateShellDocDir

generate shell doc file from given directory

Arguments

• $1 dir:String
• $2 relativeDir:String
• $3 (targetDocFile:String): the markdown file generated using shdoc
• $4 (weight:Int): weight for docsy index. Eg: 10 for top level, 20 for second level, etc.
• $5 (repositoryUrl:String): base url for src file (eg:https://github.com/fchastanet/bash-tools-framework)
• $6 (excludeFilesPattern:String): grep exclude pattern. Eg: ‘(/_.sh|/ZZZ.sh|/__all.sh)$’

Exit codes

• 0: if file has been generated
• 1: if file is empty or error

src/ShellDoc/generateShellDocsFromDir.sh

file source src/ShellDoc/generateShellDocsFromDir.sh

ShellDoc::generateShellDocsFromDir

generate doc + index

Arguments

• $1 fromDir:String
• $2 fromDirRelative:String
• $3 docDir:String
• $4 indexFile:String
• $5 (repositoryUrl:String): base url for src file (eg:https://github.com/fchastanet/bash-tools-framework)
• $6 (excludeDirectoriesPattern:String): grep exclude pattern. Eg: ‘/testsData|/_.*’
• $7 (excludeFilesPattern:String): grep exclude pattern. Eg: ‘(/_.sh|/ZZZ.sh|/__all.sh)$’
• $8 (indexFileTemplate:String): template file for index.

src/ShellDoc/installRequirementsIfNeeded.sh

file source src/ShellDoc/installRequirementsIfNeeded.sh

ShellDoc::installRequirementsIfNeeded

install requirements to execute shdoc

Environment variables

• BASH_FRAMEWORK_SHDOC_CHECK_TIMEOUT (int): default value 86400 (86400 seconds = 1 day)

Variables set

• BASH_FRAMEWORK_SHDOC_INSTALLED (String): the file created when git clone succeeded

Output on stderr

• diagnostics information is displayed

Features

• Git::cloneOrPullIfNoChanges

Warnings

• cloning is skipped if vendor/.shDocInstalled file exists
• a new check is done everyday
• repository is not updated if a change is detected

See also

• https://github.com/fchastanet/shdoc

2.28 - Namespace src/Softwares

src/Softwares

Overview

Directory src/Softwares

file source src/Softwares/installHadolint.sh

Softwares::installHadolint

install hadolint if necessary

Arguments

• $1 targetFile:String

Features

• Github::upgradeRelease

src/Softwares/installShellcheck.sh

file source src/Softwares/installShellcheck.sh

Softwares::installShellcheck

install hadolint if necessary

Arguments

• $1 targetFile:String

Features

• Github::upgradeRelease

2.29 - Namespace src/Ssh

src/Ssh

Overview

Directory src/Ssh

file source src/Ssh/checkAccess.sh

Ssh::checkAccess

check if host can accessed using ssh private key without requiring interactivity

Arguments

• $1 (host:String): the host to join
• … (args:String[]): other parameters to pass to the ssh command

Exit codes

• 1: if ssh fails
• 2: if missing host argument

Requires

• Ssh::requireSshCommand

src/Ssh/fixAuthenticityOfHostCantBeEstablished.sh

file source src/Ssh/fixAuthenticityOfHostCantBeEstablished.sh

Ssh::fixAuthenticityOfHostCantBeEstablished

Fix ssh issues

• The authenticity of host ‘www.host.net (140.82.121.4)’ can’t be established
• And Offending key for IP

Arguments

• $1 (host:String): the host to fix

Environment variables

• HOME (String):

Exit codes

• 1: is ssh-keygen fails

Requires

• Ssh::requireSshKeygenCommand
• Ssh::requireSshKeyscanCommand

src/Ssh/requireSshCommand.sh

file source src/Ssh/requireSshCommand.sh

Ssh::requireSshCommand

ensure command ssh is available

Exit codes

• 1: if ssh command not available

Output on stderr

• diagnostics information is displayed

src/Ssh/requireSshKeygenCommand.sh

file source src/Ssh/requireSshKeygenCommand.sh

Ssh::requireSshKeygenCommand

ensure command ssh-keygen is available

Exit codes

• 1: if ssh-keygen command not available

Output on stderr

• diagnostics information is displayed

src/Ssh/requireSshKeyscanCommand.sh

file source src/Ssh/requireSshKeyscanCommand.sh

Ssh::requireSshKeyscanCommand

ensure command ssh-keyscan is available

Exit codes

• 1: if ssh-keyscan command not available

Output on stderr

• diagnostics information is displayed

2.30 - Namespace src/UI

src/UI

Overview

Directory src/UI

file source src/UI/askToContinue.sh

UI::askToContinue

ask the user if he wishes to continue a process

Input: user input y or Y characters Output: displays message

Are you sure, you want to continue (y or n)?

src/UI/askToIgnoreOverwriteAbort.sh

file source src/UI/askToIgnoreOverwriteAbort.sh

UI::askToIgnoreOverwriteAbort

ask the user to ignore(i), overwrite(o) or abort(a)

Input: user input any characters

Output:

• displays message

  do you want to ignore(i), overwrite(o), abort(a) ?

• if characters entered different than [iIoOaA] displays “Invalid answer” and continue to ask

Returns:

• 0 if i or I
• 1 if o or O Exit:
• 1 if a or A

src/UI/askYesNo.sh

file source src/UI/askYesNo.sh

UI::askYesNo

Ask user to enter y or n, retry until answer is correct

Arguments

• $1 (message:String): message to display before asking

Exit codes

• 0: if yes
• 1: else

Output on stdout

• displays message

  [msg arg $1] (y or n)?

• if characters entered different than [yYnN] displays “Invalid answer” and continue to ask

src/UI/drawLine.sh

file source src/UI/drawLine.sh

UI::drawLine

draw a line with the character passed in parameter repeated depending on terminal width

Arguments

• $1 (character:String): character to use as separator (default value #)

src/UI/drawLineWithMsg.sh

file source src/UI/drawLineWithMsg.sh

UI::drawLineWithMsg

draw a line with the character passed in parameter repeated depending on terminal width including message in the middle of the screen

Arguments

• $1 (character:String): character to use as separator (default value #)
• $2 (msg:String): msg to display on the middle

Environment variables

• COLUMNS (number): of columns, if not provided compute the screen width

src/UI/requireTheme.sh

file source src/UI/requireTheme.sh

UI::requireTheme

load color theme

Function has no arguments.

Environment variables

• BASH_FRAMEWORK_THEME (String): theme to use
• LOAD_THEME (int): 0 to avoid loading theme

Exit codes

• 0: always successful

src/UI/talkToUser.sh

file source src/UI/talkToUser.sh

UI::talkToUser

display info message And wall Text to speech to tell the message if wsl and powershell available Else try to use bip

Arguments

• $1 (msg:String): message to tell
• $2 (talkScript:String): filepath to powershell talk script

Environment variables

• CAN_TALK_DURING_INSTALLATION (if): not 1 skip talking or beeping

src/UI/textLine.sh

file source src/UI/textLine.sh

UI::textLine

Display given text and complete the rest of the line with given character

Arguments

• $1 (text:String): text to display
• $2 (character:String): (default:#) character to use to complete the line

src/UI/theme.sh

file source src/UI/theme.sh

UI::theme

load colors theme constants

Arguments

• $1 (theme:String): the theme to use (default, noColor)
• $@ args:String[]

Variables set

• __ERROR_COLOR (String): indicate error status
• __INFO_COLOR (String): indicate info status
• __SUCCESS_COLOR (String): indicate success status
• __WARNING_COLOR (String): indicate warning status
• __SKIPPED_COLOR (String): indicate skipped status
• __DEBUG_COLOR (String): indicate debug status
• __HELP_COLOR (String): indicate help status
• __TEST_COLOR (String): not used
• __TEST_ERROR_COLOR (String): not used
• __HELP_TITLE_COLOR (String): used to display help title in help strings
• __HELP_OPTION_COLOR (String): used to display highlight options in help strings
• __RESET_COLOR (String): reset default color
• __HELP_EXAMPLE (String): to remove
• __HELP_TITLE (String): to remove
• __HELP_NORMAL (String): to remove

Warnings

• if tty not opened, noColor theme will be chosen

2.31 - Namespace src/Version

src/Version

Overview

Directory src/Version

file source src/Version/checkMinimal.sh

Version::checkMinimal

Check that command version is greater than expected minimal version display warning if command version greater than expected minimal version display error if command version less than expected minimal version and exit 1

Arguments

• $1 (commandName:String): command path
• $2 (argVersion:String): command line parameters to launch to get command version
• $3 (minimalVersion:String): expected minimal command version
• $4 parseVersionCallback:Function
• $5 (help:String): optional help message to display if command does not exist

Exit codes

• 0: if command version greater or equal to expected minimal version
• 1: if command version less than expected minimal version
• 2: if command does not exist

src/Version/compare.sh

file source src/Version/compare.sh

Version::compare

compare 2 version numbers

Arguments

• $1 (version1:String): version 1
• $2 (version2:String): version 2

Exit codes

• 0: if equal
• 1: if version1 > version2
• 2: else

src/Version/getCommandVersionFromPlainText.sh

file source src/Version/getCommandVersionFromPlainText.sh

Version::getCommandVersionFromPlainText

extract software version number

Arguments

• $1 (command:String): the command that will be called with –version parameter
• $2 (argVersion:String): allows to override default –version parameter

src/Version/githubApiExtractVersion.sh

file source src/Version/githubApiExtractVersion.sh

Version::githubApiExtractVersion

extract version number from github api

Function has no arguments.

Exit codes

• 1: if jq or Version::parse fails

Input on stdin

• json result of github API

Output on stdout

• the version parsed

Requires

• Linux::requireJqCommand

src/Version/parse.sh

file source src/Version/parse.sh

Version::parse

filter to keep only version number from a string

Arguments

• … (files:String[]): the files to filter

Exit codes

• • if one of the filter command fails

Input on stdin

• you can use stdin as alternative to files argument

Output on stdout

• the filtered content

2.32 - Namespace src/Web

src/Web

Overview

Directory src/Web

file source src/Web/getReleases.sh

Web::getReleases

Retrieve the latest version number of a web release

Arguments

• $1 (releaseListUrl:String): the url from which version list can be retrieved

Environment variables

• CURL_CONNECT_TIMEOUT (number): of seconds before giving up host connection

Output on stdout

• log messages about retry

src/Web/upgradeRelease.sh

file source src/Web/upgradeRelease.sh

Web::upgradeRelease

upgrade given binary to latest release using retry

releasesUrl argument : the placeholder @latestVersion@ will be replaced by the latest release version

Arguments

• $1 (targetFile:String): target binary file (eg: /usr/local/bin/kind)
• $2 (releasesUrl:String): url on which we can query all available versions (eg: “https://go.dev/dl/?mode=json")
• $3 (downloadReleaseUrl:String): url from which the software will be downloaded (eg: https://storage.googleapis.com/golang/go@latestVersion@.linux-amd64.tar.gz)
• $4 (softVersionArg:String): parameter to add to existing command to compute current version
• $5 (exactVersion:String): if you want to retrieve a specific version instead of the latest

Environment variables

• FILTER_LAST_VERSION_CALLBACK (a): callback to filter the latest version from releasesUrl
• SOFT_VERSION_CALLBACK (a): callback to execute command version
• PARSE_VERSION_CALLBACK (a): callback to parse the version of the existing command
• INSTALL_CALLBACK (a): callback to install the software downloaded
• CURL_CONNECT_TIMEOUT (number): of seconds before giving up host connection
• VERSION_PLACEHOLDER (a): placeholder to replace in downloadReleaseUrl (default: @latestVersion@)

Output on stdout

• log messages about retry, install, upgrade

3 - Framework Overview

This framework is a collection of several bash functions and commands that helps you to lint files, generate shell documentation, compile bash files, and many more, …

The Bash Tools Framework provides 150+ unit-tested functions organized by namespace. This section provides an overview of the available namespaces and their key functions.

1. Generated Documentation

The complete function reference documentation is automatically generated from source code using shdoc. This documentation includes detailed information about:

• Function parameters
• Return values
• Exit codes
• Usage examples
• Environment variables

To generate the documentation:

bin/doc

2. Framework Overview

Here an excerpt of the namespaces available in Bash tools framework:

• Apt: several functions to abstract the use of ubuntu apt-get function. these functions are using some default arguments and manage retry automatically.
  • Linux::Apt::addRepository
  • Linux::Apt::install
  • Linux::Apt::remove
  • Linux::Apt::update
• Args: functions to ease some recurrent arguments like -h|–help to display help
• Array: functions to ease manipulation of bash arrays like Array::clone or Array::contains that checks if an element is contained in an array
• Assert: various checks like
  • Assert::expectUser, Assert::expectNonRootUser, Assert::expectRootUser exits with message if current user is not the expected one
  • Assert::commandExists checks if command specified exists or exits with error message if not
  • Assert::windows determines if the script is executed under windows (git bash, wsl)
  • Assert::validPath checks if path provided is a valid linux path, it doesn’t have to exist yet
  • Assert::bashFrameworkFunction checks if given name respects naming convention of this framework’s functions
  • …
• Backup::file, Backup::dir allows to create a backup of a file or a directory in a folder configured in a .env file managed by the framework (see Env::requireLoad)
• Aws: Aim is to abstract the use of some aws cli commands, for the moment only Aws::imageExists has been implemented allowing to check that a docker image exists with tags provided on AWS ecr(AWS docker repository)
• Bats::installRequirementsIfNeeded allows to install bats vendor requirements for this project, it uses mainly the useful function Git::shallowClone
• Cache : various cache methods to provide files or env variable with expiration management
• Command::captureOutputAndExitCode calls a command capturing output and exit code and displaying it also to error output to follow command’s progress
• Conf : allows to manage the loading of .env file that contains configuration used by some functions of this framework.
• Database : abstraction of several mysql queries, like:
  • Database::dump dump db limited to optional table list
  • Database::query mysql query on a given db
  • Database::dropTable drop table if exists
  • Database::dropDb drop database if exists
  • Database::createDb create database if not already existing
  • Database::isTableExists check if table exists on given db
  • Database::ifDbExists check if given database exists
  • all these methods need to call Database::newInstance in order to reference target db connection
• Dns : various methods like Dns::pingHost or allowing etc/hosts manipulation.
• Docker : various docker cli abstractions that allowed to construct bin/buildPushDockerImage command.
• Env : functions allowing to load env variables or to alter them like Env::pathAppend allowing to add a bin path to PATH variable
• File : files and file paths manipulations.
• Filters : various functions to filter files using grep, awk or sed eg: Filters::bashFrameworkFunctions allows to find all the bash framework functions used in a file
• Git : provides git abstractions like Git::cloneOrPullIfNoChange, Git::pullIfNoChanges or Git::shallowClone
• Install : copy directory or file, backup them before if needed.
• Github : major feature is install automatically latest binary release using Github::upgradeRelease
• Log::display\* output colored message on error output and log the message
  • Log::fatal error message in red bold and exits with code 1
  • Log::displayError error message in red
  • Log::displayWarning warning message in yellow
  • Log::displayInfo info message in white on lightBlue
  • Log::displaySuccess success message in green
  • Log::displayDebug debug message in gray
• Log::log\* output message in a log file
  • Log::logError
  • Log::logWarning
  • Log::logInfo
  • Log::logSuccess
  • Log::logDebug
• Log::rotate automatically rotates the log file, this function is used internally by Log::log\* functions.
• OS: ubuntu related functions
• Profiles: methods mainly used by Bash-dev-env project that allows to indicate scripts list to install with the ability to include all the dependencies recursively. This file src/Profiles/lintDefinitions.sh is the precursor of a first bash interface implementation.
• Retry: retry a command on failure easily
• ShellDoc: this framework shell documentation generation
• Ssh: mainly Ssh::fixAuthenticityOfHostCantBeEstablished
• Sudo: executes command as sudo if needed
• UI
  • UI::askToContinue ask the user if he wishes to continue a process
  • UI::askYesNo ask the user a confirmation
  • UI::askToIgnoreOverwriteAbort ask the user to ignore(i), overwrite(o) or abort(a)
• Version
  • Version::checkMinimal ensure that command exists with expected version
  • Version::compare compares two versions
• Wsl: commands wslvar and wslpath are expensive, avoid multiple calls using cache
• src/_standalone regroups methods that do not respect framework naming conventions like assert_lines_count that is used to assert the number of lines of output in bats tests

3. Development Environment

3.1. Precommit hook

This repository uses pre-commit software to ensure every commits respects a set of rules specified by the .pre-commit-config.yaml file. It supposes pre-commit software is installed in your environment.

You also have to execute the following command to enable it:

pre-commit install --hook-type pre-commit --hook-type pre-push

3.2. UT

All the methods of this framework are unit tested, you can run the unit tests using the following command

./test.sh scrasnups/build:bash-tools-ubuntu-5.3 -r src -j 30

Launch UT on different environments:

./test.sh scrasnups/build:bash-tools-ubuntu-4.4 -r src -j 30
./test.sh scrasnups/build:bash-tools-ubuntu-5.0 -r src -j 30
./test.sh scrasnups/build:bash-tools-ubuntu-5.3 -r src -j 30
./test.sh scrasnups/build:bash-tools-alpine-4.4 -r src -j 30
./test.sh scrasnups/build:bash-tools-alpine-5.0 -r src -j 30
./test.sh scrasnups/build:bash-tools-alpine-5.3 -r src -j 30

3.3. Debug bats

use the following command:

vendor/bats/bin/bats -r src/Conf/loadNearestFile.bats --trace --verbose-run --filter "Conf::loadNearestFileFileFoundInDir1"

3.4. connect to container manually

Alpine with bash version 4.4

docker run --rm -it -w /bash -v "$(pwd):/bash" --entrypoint="" --user 1000:1000 bash-tools-alpine-4.4-user bash

Ubuntu with bash version 5.1

docker run --rm -it -w /bash -v "$(pwd):/bash" --entrypoint="" --user 1000:1000 bash-tools-ubuntu-5.1-user bash

3.5. auto generated bash doc

generated by running

bin/doc

3.6. github page

The web page uses Hugo with the Docsy theme to generate a static documentation site.

To preview the website locally, you need to clone my-documents repository

git clone git@github.com:fchastanet/my-documents.git

And run the following command from the root of this repository:

SITE=bash-tools-framework make start-site

Navigate to http://localhost:1313/bash-tools-framework/

4. Troubleshooting

4.1. compile.bats embed not working on alpine investigation

exit code 127 is returned but process seems to go until the end. This error only occurs on alpine.

commands to compile and debug:

# run docker alpine interactively
docker run --rm -it -w /bash -v "$(pwd):/bash" --entrypoint="" --user 1000:1000 build:bash-tools-alpine-4.4-user bash

# launch bats test that fails
vendor/bats/bin/bats -r src/_binaries/compile.bats --filter embed

# launch directly compile command that returns the same exit code
bin/compile src/_binaries/testsData/bin/embed.sh --template-dir src --bin-dir bin --root-dir $PWD --src-dir src/_binaries/testsData/src
echo $? # prints 127

# try to get more logs
KEEP_TEMP_FILES=1 BASH_FRAMEWORK_DISPLAY_LEVEL=4 bin/compile \
  src/_binaries/testsData/bin/embed.sh \
  --template-dir src \
  --bin-dir bin \
  --root-dir "${PWD}" \
  --src-dir src/_binaries/testsData/src

# try to use strace
docker run --rm -it \
  -w /bash -v "$(pwd):/bash" \
  --entrypoint="" \
  build:bash-tools-alpine-4.4-user bash
apk update
apk add strace

Strace didn’t helped me a lot. But as I added recently this option shopt -u lastpipe, I removed it from compile binary and the issue disappeared.

As I was suspecting the while piped inside Compiler::Embed::inject. I added the following code in this function to remove the tracing just after the error occurs:

trap 'set +x' EXIT
set -x

It allows me to find that the last command executed was read -r line.

Finally I understand that the issue comes when read -r line exits with code 1 because of end of file.

previous simplified code:

cat file | {
  local line
  while IFS="" read -r line; do
    # ...
  done
}

Resulting in exit code 127 because of pipe and shopt -u lastpipe.

Fixed code is to remove error if :

cat file | {
  local line
  while true; do
    local status=0
    IFS="" read -r line || status=$?
    if [[ "${status}" = "1" ]]; then
      # end of file
      return 0
    elif [[ "${status}" != "0" ]]; then
      # other error
      return "${status}"
    fi
    # ...
  done
}

5. External Resources

For comprehensive guides on Bash best practices, please refer to these documents:

• General Bash Best Practices - Core Bash scripting practices
• Linux Commands Best Practices - Effective Linux command usage
• Bats Best Practices - Testing best practices with Bats

6. Related Projects

This framework is part of a suite of projects:

• My Documents
• Bash Tools
• Bash Dev Env
• Bash Compiler

4 - Commands

The Bash Tools Framework provides several command-line tools for linting, building, and managing bash projects.

1. Compile command

The framework works with bash-compiler, a GoLang implementation that generates standalone executables from YAML definitions.

1.1. Usage

Using bash-compiler binary:

export PATH=$PATH:/home/wsl/fchastanet/bash-compiler/bin
FRAMEWORK_ROOT_DIR=$(pwd) bash-compiler \
  src/_binaries/shellcheckLint/shellcheckLint-binary.yaml

Using Go interpreter (must be executed from bash-compiler folder):

export FRAMEWORK_ROOT_DIR=/home/wsl/fchastanet/bash-dev-env/vendor/bash-tools-framework
go run ./cmd/bash-compiler "${FRAMEWORK_ROOT_DIR}/src/_binaries/shellcheckLint/shellcheckLint-binary.yaml"

Compile all *-binary.yaml files at once:

export FRAMEWORK_ROOT_DIR=/home/wsl/fchastanet/bash-dev-env/vendor/bash-tools-framework
go run ./cmd/bash-compiler $(find "${FRAMEWORK_ROOT_DIR}/src/_binaries" -name '*-binary.yaml' -print)

See Bash Compiler documentation for more information.

1.2. Example: Creating a Command

To create a new command using the framework:

1. Create a YAML definition in src/_binaries/myCommand/myCommand-binary.yaml
2. Define the command’s options and main script
3. Compile using bash-compiler
4. The generated binary will be placed in bin/myCommand

See the framework command template for a starting point.

2. Build Tools

2.1. bin/installRequirements

bin/installRequirements script will install the following libraries inside vendor folder:

• bats-core/bats-core
• bats-core/bats-support
• bats-core/bats-assert
• Flamefire/bats-mock
• hadolint
• shellcheck
• shdoc

bin/doc script will install:

• reconquest/shdoc
• hadolint
• shellcheck

Dependencies are automatically installed when first used. To avoid checking for libraries update and have an impact on performance, a file is created in vendor dir.

• vendor/.shdocInstalled
• vendor/.batsInstalled

You can remove these files to force the update of the libraries, or just wait 24 hours for the timeout to expire 😉

SYNOPSIS:
    Installs requirements.

USAGE: installRequirements [OPTIONS]
USAGE: installRequirements [--help|-h] [--config]
  [--bash-framework-config <bash-framework-config>] [--verbose|-v] [-vv] [-vvv]
  [--log-level <log-level>] [--log-file <log-file>]
  [--display-level <display-level>] [--no-color] [--theme <theme>] [--version]
  [--quiet|-q]

GLOBAL OPTIONS:
  --help, -h {single}
    Displays this command help
  --config {single}
    Displays configuration
  --bash-framework-config <bash-framework-config> {single}
    Use alternate bash framework configuration.
  --verbose, -v {single}
    Info level verbose mode (alias of --display-level INFO)
  -vv {single}
    Debug level verbose mode (alias of --display-level DEBUG)
  -vvv {single}
    Trace level verbose mode (alias of --display-level TRACE)
  --log-level <log-level> {single}
    Set log level
    Possible values: 
      - OFF
      - ERR
      - ERROR
      - WARN
      - WARNING
      - INFO
      - DEBUG
      - TRACE
    Default value: OFF
  --log-file <log-file> {single}
    Set log file
    Default value: /bash/bin/logs/installRequirements.log
  --display-level <display-level> {single}
    Set display level
    Possible values: 
      - OFF
      - ERR
      - ERROR
      - WARN
      - WARNING
      - INFO
      - DEBUG
      - TRACE
    Default value: INFO
  --no-color {single}
    Produce monochrome output. alias of --theme noColor.
  --theme <theme> {single}
    Choose color theme - default-force means colors will be produced even if
    command is piped.
    Possible values: 
      - default
      - default-force
      - noColor
    Default value: default
  --version {single}
    Print version information and quit.
  --quiet, -q {single}
    Quiet mode, doesn't display any output.


DESCRIPTION:
Installs requirements:

- bats
- hadolint
- shellcheck

VERSION: 3.0

AUTHOR: [François Chastanet](https://github.com/fchastanet)

SOURCE FILE: https://github.com/fchastanet/bash-tools-framework/tree/master/src/_binaries/installRequirements/installRequirements-binary.yaml

LICENSE: MIT License
Copyright (c) 2024-now François Chastanet

2.2. bin/findShebangFiles

Find files with shebang in a directory.

SYNOPSIS:
    find all shebang files of this repository

USAGE: findShebangFiles [OPTIONS]
USAGE: findShebangFiles [--help|-h] [--config]
  [--bash-framework-config <bash-framework-config>] [--verbose|-v] [-vv] [-vvv]
  [--log-level <log-level>] [--log-file <log-file>]
  [--display-level <display-level>] [--no-color] [--theme <theme>] [--version]
  [--quiet|-q]

GLOBAL OPTIONS:
  --help, -h {single}
    Displays this command help
  --config {single}
    Displays configuration
  --bash-framework-config <bash-framework-config> {single}
    Use alternate bash framework configuration.
  --verbose, -v {single}
    Info level verbose mode (alias of --display-level INFO)
  -vv {single}
    Debug level verbose mode (alias of --display-level DEBUG)
  -vvv {single}
    Trace level verbose mode (alias of --display-level TRACE)
  --log-level <log-level> {single}
    Set log level
    Possible values: 
      - OFF
      - ERR
      - ERROR
      - WARN
      - WARNING
      - INFO
      - DEBUG
      - TRACE
    Default value: OFF
  --log-file <log-file> {single}
    Set log file
    Default value: /bash/bin/logs/findShebangFiles.log
  --display-level <display-level> {single}
    Set display level
    Possible values: 
      - OFF
      - ERR
      - ERROR
      - WARN
      - WARNING
      - INFO
      - DEBUG
      - TRACE
    Default value: INFO
  --no-color {single}
    Produce monochrome output. alias of --theme noColor.
  --theme <theme> {single}
    Choose color theme - default-force means colors will be produced even if
    command is piped.
    Possible values: 
      - default
      - default-force
      - noColor
    Default value: default
  --version {single}
    Print version information and quit.
  --quiet, -q {single}
    Quiet mode, doesn't display any output.


DESCRIPTION:
Display list of all files having a bash shebang in the current repository.

You can apply a command to all these files by providing arguments

Example: Add execution bit to all files with a bash shebang
findShebangFiles chmod +x

VERSION: 3.0

AUTHOR: [François Chastanet](https://github.com/fchastanet)

SOURCE FILE: https://github.com/fchastanet/bash-tools-framework/tree/master/src/_binaries/findShebangFiles/findShebangFiles-binary.yaml

LICENSE: MIT License
Copyright (c) 2023-now François Chastanet

2.3. bin/buildPushDockerImage

Build and push Docker images with proper tagging and caching.

SYNOPSIS:
    Lint bash files using shellcheck.

USAGE: buildPushDockerImage [OPTIONS]
USAGE: buildPushDockerImage [--help|-h] [--config]
  [--bash-framework-config <bash-framework-config>] [--verbose|-v] [-vv] [-vvv]
  [--log-level <log-level>] [--log-file <log-file>]
  [--display-level <display-level>] [--no-color] [--theme <theme>] [--version]
  [--quiet|-q] [--push] [--vendor <vendor>] [--bash-version <bash-version>]
  [--bash-base-image <bash-base-image>]

GLOBAL OPTIONS:
  --help, -h {single}
    Displays this command help
  --config {single}
    Displays configuration
  --bash-framework-config <bash-framework-config> {single}
    Use alternate bash framework configuration.
  --verbose, -v {single}
    Info level verbose mode (alias of --display-level INFO)
  -vv {single}
    Debug level verbose mode (alias of --display-level DEBUG)
  -vvv {single}
    Trace level verbose mode (alias of --display-level TRACE)
  --log-level <log-level> {single}
    Set log level
    Possible values: 
      - OFF
      - ERR
      - ERROR
      - WARN
      - WARNING
      - INFO
      - DEBUG
      - TRACE
    Default value: OFF
  --log-file <log-file> {single}
    Set log file
    Default value: /bash/bin/logs/buildPushDockerImage.log
  --display-level <display-level> {single}
    Set display level
    Possible values: 
      - OFF
      - ERR
      - ERROR
      - WARN
      - WARNING
      - INFO
      - DEBUG
      - TRACE
    Default value: INFO
  --no-color {single}
    Produce monochrome output. alias of --theme noColor.
  --theme <theme> {single}
    Choose color theme - default-force means colors will be produced even if
    command is piped.
    Possible values: 
      - default
      - default-force
      - noColor
    Default value: default
  --version {single}
    Print version information and quit.
  --quiet, -q {single}
    Quiet mode, doesn't display any output.

OPTIONS:
  --push {single}
    if provided, push the image to the registry
  --vendor <vendor> {single}
    vendor image to use
    Possible values: 
      - alpine: alpine based docker image
      - ubuntu: ubuntu based docker image
    Default value: ubuntu
  --bash-version <bash-version> {single}
    version of bash to use
    Possible values: 
      - 4.4
      - 5.0
      - 5.1
      - 5.2
    Default value: 5.2
  --bash-base-image <bash-base-image> {single}
    bash bash image to use (eg: ubuntu:20.04, amd64/bash:4.4-alpine3.18)
    Default value: ubuntu:20.04


DESCRIPTION:
Pull, build and push docker image:
- pull previous docker image from docker hub if exists
- build new image using previous image as cache
- tag built image
- push it to docker registry

additional docker build options can be passed
  via DOCKER_BUILD_OPTIONS env variable

INTERNAL

VERSION: 3.0

AUTHOR: [François Chastanet](https://github.com/fchastanet)

SOURCE FILE: https://github.com/fchastanet/bash-tools-framework/tree/master/src/_binaries/buildPushDockerImage/buildPushDockerImage-binary.yaml

LICENSE: MIT License
Copyright (c) 2023-now François Chastanet

2.4. bin/doc

Generate markdown documentation for the framework from source code comments. This command:

• Extracts shdoc annotations from .sh files
• Generates comprehensive documentation
• Creates function reference pages

SYNOPSIS:
    Generate markdown documentation.

USAGE: doc [OPTIONS]
USAGE: doc [--ci] [--help|-h] [--config]
  [--bash-framework-config <bash-framework-config>] [--verbose|-v] [-vv] [-vvv]
  [--log-level <log-level>] [--log-file <log-file>]
  [--display-level <display-level>] [--no-color] [--theme <theme>] [--version]
  [--quiet|-q]

OPTIONS:
  --ci {single}
    Activate continuous integration mode (tmp folder not shared with host)


GLOBAL OPTIONS:
  --help, -h {single}
    Displays this command help
  --config {single}
    Displays configuration
  --bash-framework-config <bash-framework-config> {single}
    Use alternate bash framework configuration.
  --verbose, -v {single}
    Info level verbose mode (alias of --display-level INFO)
  -vv {single}
    Debug level verbose mode (alias of --display-level DEBUG)
  -vvv {single}
    Trace level verbose mode (alias of --display-level TRACE)
  --log-level <log-level> {single}
    Set log level
    Possible values: 
      - OFF
      - ERR
      - ERROR
      - WARN
      - WARNING
      - INFO
      - DEBUG
      - TRACE
    Default value: OFF
  --log-file <log-file> {single}
    Set log file
    Default value: /bash/bin/logs/doc.log
  --display-level <display-level> {single}
    Set display level
    Possible values: 
      - OFF
      - ERR
      - ERROR
      - WARN
      - WARNING
      - INFO
      - DEBUG
      - TRACE
    Default value: INFO
  --no-color {single}
    Produce monochrome output. alias of --theme noColor.
  --theme <theme> {single}
    Choose color theme - default-force means colors will be produced even if
    command is piped.
    Possible values: 
      - default
      - default-force
      - noColor
    Default value: default
  --version {single}
    Print version information and quit.
  --quiet, -q {single}
    Quiet mode, doesn't display any output.


DESCRIPTION:
INTERNAL TOOL

VERSION: 3.0

AUTHOR: [François Chastanet](https://github.com/fchastanet)

SOURCE FILE: https://github.com/fchastanet/bash-tools-framework/tree/master/src/_binaries/doc/doc-binary.yaml

LICENSE: MIT License
Copyright (c) 2022-now François Chastanet

2.5. test.sh

Run unit tests using bats inside Docker container with needed dependencies.

# Run all tests on Ubuntu Bash 5.3
./test.sh scrasnups/build:bash-tools-ubuntu-5.3 -r src -j 30

# Run specific test file
./test.sh scrasnups/build:bash-tools-ubuntu-5.3 src/Array/contains.bats

# Run on different environments
./test.sh scrasnups/build:bash-tools-ubuntu-4.4 -r src -j 30
./test.sh scrasnups/build:bash-tools-ubuntu-5.0 -r src -j 30
./test.sh scrasnups/build:bash-tools-ubuntu-5.3 -r src -j 30
./test.sh scrasnups/build:bash-tools-alpine-4.4 -r src -j 30
./test.sh scrasnups/build:bash-tools-alpine-5.0 -r src -j 30
./test.sh scrasnups/build:bash-tools-alpine-5.3 -r src -j 30

3. Linters

3.1. bin/frameworkLint

Lint files of the current repository to ensure framework conventions are followed.

This linter is used in pre-commit hooks. See .pre-commit-config.yaml.

SYNOPSIS:
    Lint files of the current repository to ensure framework conventions
    are followed.


USAGE: frameworkLint [OPTIONS]
USAGE: frameworkLint [--help|-h] [--config]
  [--bash-framework-config <bash-framework-config>] [--verbose|-v] [-vv] [-vvv]
  [--log-level <log-level>] [--log-file <log-file>]
  [--display-level <display-level>] [--no-color] [--theme <theme>] [--version]
  [--quiet|-q] [--format <format>]
  [--expected-warnings-count <expected-warnings-count>]

GLOBAL OPTIONS:
  --help, -h {single}
    Displays this command help
  --config {single}
    Displays configuration
  --bash-framework-config <bash-framework-config> {single}
    Use alternate bash framework configuration.
  --verbose, -v {single}
    Info level verbose mode (alias of --display-level INFO)
  -vv {single}
    Debug level verbose mode (alias of --display-level DEBUG)
  -vvv {single}
    Trace level verbose mode (alias of --display-level TRACE)
  --log-level <log-level> {single}
    Set log level
    Possible values: 
      - OFF
      - ERR
      - ERROR
      - WARN
      - WARNING
      - INFO
      - DEBUG
      - TRACE
    Default value: OFF
  --log-file <log-file> {single}
    Set log file
    Default value: /bash/bin/logs/frameworkLint.log
  --display-level <display-level> {single}
    Set display level
    Possible values: 
      - OFF
      - ERR
      - ERROR
      - WARN
      - WARNING
      - INFO
      - DEBUG
      - TRACE
    Default value: INFO
  --no-color {single}
    Produce monochrome output. alias of --theme noColor.
  --theme <theme> {single}
    Choose color theme - default-force means colors will be produced even if
    command is piped.
    Possible values: 
      - default
      - default-force
      - noColor
    Default value: default
  --version {single}
    Print version information and quit.
  --quiet, -q {single}
    Quiet mode, doesn't display any output.

OPTIONS:
  --format <format> {single}
    Define output format of this command.
    Possible values: 
      - plain
      - checkstyle
    Default value: plain
  --expected-warnings-count <expected-warnings-count> {single}
    Specify expected warning count (default: 0)


DESCRIPTION:
Lint files of the current repository
  - check if all Namespace::functions are existing in the framework
  - check that function defined in a .sh is correctly named
  - check each function has a bats file associated

  - shdoc     - check that shdoc valid annotations are used
    - check that @require function matches naming convention and exists
    - check that at least @description is provided

VERSION: 3.0

AUTHOR: [François Chastanet](https://github.com/fchastanet)

SOURCE FILE: https://github.com/fchastanet/bash-tools-framework/tree/master/src/_binaries/frameworkLint/frameworkLint-binary.yaml

LICENSE: MIT License
Copyright (c) 2023-now François Chastanet

3.2. bin/dockerLint

Hadolint wrapper with automatic installation of hadolint.

SYNOPSIS:
    Lint docker files of the given directory using hadolint.

USAGE: dockerLint [OPTIONS] [ARGUMENTS]
USAGE: dockerLint [--help|-h] [--config]
  [--bash-framework-config <bash-framework-config>] [--verbose|-v] [-vv] [-vvv]
  [--log-level <log-level>] [--log-file <log-file>]
  [--display-level <display-level>] [--no-color] [--theme <theme>] [--version]
  [--quiet|-q]

ARGUMENTS:
  [hadolintArguments {list} (optional)]    hadolint arguments

GLOBAL OPTIONS:
  --help, -h {single}
    Displays this command help
  --config {single}
    Displays configuration
  --bash-framework-config <bash-framework-config> {single}
    Use alternate bash framework configuration.
  --verbose, -v {single}
    Info level verbose mode (alias of --display-level INFO)
  -vv {single}
    Debug level verbose mode (alias of --display-level DEBUG)
  -vvv {single}
    Trace level verbose mode (alias of --display-level TRACE)
  --log-level <log-level> {single}
    Set log level
    Possible values: 
      - OFF
      - ERR
      - ERROR
      - WARN
      - WARNING
      - INFO
      - DEBUG
      - TRACE
    Default value: OFF
  --log-file <log-file> {single}
    Set log file
    Default value: /bash/bin/logs/dockerLint.log
  --display-level <display-level> {single}
    Set display level
    Possible values: 
      - OFF
      - ERR
      - ERROR
      - WARN
      - WARNING
      - INFO
      - DEBUG
      - TRACE
    Default value: INFO
  --no-color {single}
    Produce monochrome output. alias of --theme noColor.
  --theme <theme> {single}
    Choose color theme - default-force means colors will be produced even if
    command is piped.
    Possible values: 
      - default
      - default-force
      - noColor
    Default value: default
  --version {single}
    Print version information and quit.
  --quiet, -q {single}
    Quiet mode, doesn't display any output.


DESCRIPTION:
- installs new hadolint version(>2.12.0) automatically
- lint this project files using default files filter

HADOLINT HELP:

hadolint - Dockerfile Linter written in Haskell

Usage: hadolint [-v|--version] [-c|--config FILENAME] [DOCKERFILE...] 
                [--file-path-in-report FILEPATHINREPORT] [--no-fail] 
                [--no-color] [-V|--verbose] [-f|--format ARG] [--error RULECODE]
                [--warning RULECODE] [--info RULECODE] [--style RULECODE] 
                [--ignore RULECODE] 
                [--trusted-registry REGISTRY (e.g. docker.io)] 
                [--require-label LABELSCHEMA (e.g. maintainer:text)] 
                [--strict-labels] [--disable-ignore-pragma] 
                [-t|--failure-threshold THRESHOLD]

  Lint Dockerfile for errors and best practices

Available options:
  -h,--help                Show this help text
  -v,--version             Show version
  -c,--config FILENAME     Path to the configuration file
  --file-path-in-report FILEPATHINREPORT
                           The file path referenced in the generated report.
                           This only applies for the 'checkstyle' format and is
                           useful when running Hadolint with Docker to set the
                           correct file path.
  --no-fail                Don't exit with a failure status code when any rule
                           is violated
  --no-color               Don't colorize output
  -V,--verbose             Enables verbose logging of hadolint's output to
                           stderr
  -f,--format ARG          The output format for the results [tty | json |
                           checkstyle | codeclimate | gitlab_codeclimate | gnu |
                           codacy | sonarqube | sarif] (default: tty)
  --error RULECODE         Make the rule `RULECODE` have the level `error`
  --warning RULECODE       Make the rule `RULECODE` have the level `warning`
  --info RULECODE          Make the rule `RULECODE` have the level `info`
  --style RULECODE         Make the rule `RULECODE` have the level `style`
  --ignore RULECODE        A rule to ignore. If present, the ignore list in the
                           config file is ignored
  --trusted-registry REGISTRY (e.g. docker.io)
                           A docker registry to allow to appear in FROM
                           instructions
  --require-label LABELSCHEMA (e.g. maintainer:text)
                           The option --require-label=label:format makes
                           Hadolint check that the label `label` conforms to
                           format requirement `format`
  --strict-labels          Do not permit labels other than specified in
                           `label-schema`
  --disable-ignore-pragma  Disable inline ignore pragmas `# hadolint
                           ignore=DLxxxx`
  -t,--failure-threshold THRESHOLD
                           Exit with failure code only when rules with a
                           severity equal to or above THRESHOLD are violated.
                           Accepted values: [error | warning | info | style |
                           ignore | none] (default: info)

VERSION: 3.0

AUTHOR: [François Chastanet](https://github.com/fchastanet)

SOURCE FILE: https://github.com/fchastanet/bash-tools-framework/tree/master/src/_binaries/dockerLint/dockerLint-binary.yaml

LICENSE: MIT License
Copyright (c) 2022-now François Chastanet

3.3. bin/shellcheckLint

ShellCheck wrapper with automatic installation of ShellCheck.

SYNOPSIS:
    Lint bash files using shellcheck.

USAGE: shellcheckLint [OPTIONS] [ARGUMENTS]
USAGE: shellcheckLint [--help|-h] [--config]
  [--bash-framework-config <bash-framework-config>] [--verbose|-v] [-vv] [-vvv]
  [--log-level <log-level>] [--log-file <log-file>]
  [--display-level <display-level>] [--no-color] [--theme <theme>] [--version]
  [--quiet|-q] [--format|-f <format>] [--staged] [--xargs]

ARGUMENTS:
  [shellcheckFiles {list} (optional)]    files to validate with shellcheck.
    If not provided, all files from git repository which are beginning
    with a bash shebang, unless --staged option is provided.


GLOBAL OPTIONS:
  --help, -h {single}
    Displays this command help
  --config {single}
    Displays configuration
  --bash-framework-config <bash-framework-config> {single}
    Use alternate bash framework configuration.
  --verbose, -v {single}
    Info level verbose mode (alias of --display-level INFO)
  -vv {single}
    Debug level verbose mode (alias of --display-level DEBUG)
  -vvv {single}
    Trace level verbose mode (alias of --display-level TRACE)
  --log-level <log-level> {single}
    Set log level
    Possible values: 
      - OFF
      - ERR
      - ERROR
      - WARN
      - WARNING
      - INFO
      - DEBUG
      - TRACE
    Default value: OFF
  --log-file <log-file> {single}
    Set log file
    Default value: /bash/bin/logs/shellcheckLint.log
  --display-level <display-level> {single}
    Set display level
    Possible values: 
      - OFF
      - ERR
      - ERROR
      - WARN
      - WARNING
      - INFO
      - DEBUG
      - TRACE
    Default value: INFO
  --no-color {single}
    Produce monochrome output. alias of --theme noColor.
  --theme <theme> {single}
    Choose color theme - default-force means colors will be produced even if
    command is piped.
    Possible values: 
      - default
      - default-force
      - noColor
    Default value: default
  --version {single}
    Print version information and quit.
  --quiet, -q {single}
    Quiet mode, doesn't display any output.

SPECIFIC OPTIONS:
  --format, -f <format> {single}
    define output format of this command
    Possible values: 
      - checkstyle
      - diff
      - gcc
      - json
      - json1
      - quiet
      - tty
    Default value: tty
  --staged {single}
    lint only staged git files(files added to file list to be committed)
    and which are beginning with a bash shebang.

  --xargs {single}
    uses parallelization(using xargs command) only if tty format


DESCRIPTION:
shellcheck wrapper that will:

- install new shellcheck version(0.9.0) automatically

- by default, lint all git files of this project
    which are beginning with a bash shebang
    except if the option --staged is passed

Special configuration .shellcheckrc:
  use the following line in your .shellcheckrc file to exclude
  some files from being checked (use grep -E syntax)   exclude=^bin/compile$

SHELLCHECK HELP
Usage: shellcheck [OPTIONS...] FILES...
  -a                  --check-sourced            Include warnings from sourced files
  -C[WHEN]            --color[=WHEN]             Use color (auto, always, never)
  -i CODE1,CODE2..    --include=CODE1,CODE2..    Consider only given types of warnings
  -e CODE1,CODE2..    --exclude=CODE1,CODE2..    Exclude types of warnings
                      --extended-analysis=bool   Perform dataflow analysis (default true)
  -f FORMAT           --format=FORMAT            Output format (checkstyle, diff, gcc, json, json1, quiet, tty)
                      --list-optional            List checks disabled by default
                      --norc                     Don't look for .shellcheckrc files
                      --rcfile=RCFILE            Prefer the specified configuration file over searching for one
  -o check1,check2..  --enable=check1,check2..   List of optional checks to enable (or 'all')
  -P SOURCEPATHS      --source-path=SOURCEPATHS  Specify path when looking for sourced files ("SCRIPTDIR" for script's dir)
  -s SHELLNAME        --shell=SHELLNAME          Specify dialect (sh, bash, dash, ksh, busybox)
  -S SEVERITY         --severity=SEVERITY        Minimum severity of errors to consider (error, warning, info, style)
  -V                  --version                  Print version information
  -W NUM              --wiki-link-count=NUM      The number of wiki links to show, when applicable
  -x                  --external-sources         Allow 'source' outside of FILES
                      --help                     Show this usage summary and exit


VERSION: 3.0

AUTHOR: [François Chastanet](https://github.com/fchastanet)

SOURCE FILE: https://github.com/fchastanet/bash-tools-framework/tree/master/src/_binaries/shellcheckLint/shellcheckLint-binary.yaml

LICENSE: MIT License
Copyright (c) 2022-now François Chastanet

3.4. bin/awkLint

Lint all files with .awk extension in specified folder.

SYNOPSIS:
    lint awk files

USAGE: awkLint [OPTIONS]
USAGE: awkLint [--help|-h] [--config]
  [--bash-framework-config <bash-framework-config>] [--verbose|-v] [-vv] [-vvv]
  [--log-level <log-level>] [--log-file <log-file>]
  [--display-level <display-level>] [--no-color] [--theme <theme>] [--version]
  [--quiet|-q]

GLOBAL OPTIONS:
  --help, -h {single}
    Displays this command help
  --config {single}
    Displays configuration
  --bash-framework-config <bash-framework-config> {single}
    Use alternate bash framework configuration.
  --verbose, -v {single}
    Info level verbose mode (alias of --display-level INFO)
  -vv {single}
    Debug level verbose mode (alias of --display-level DEBUG)
  -vvv {single}
    Trace level verbose mode (alias of --display-level TRACE)
  --log-level <log-level> {single}
    Set log level
    Possible values: 
      - OFF
      - ERR
      - ERROR
      - WARN
      - WARNING
      - INFO
      - DEBUG
      - TRACE
    Default value: OFF
  --log-file <log-file> {single}
    Set log file
    Default value: /bash/bin/logs/awkLint.log
  --display-level <display-level> {single}
    Set display level
    Possible values: 
      - OFF
      - ERR
      - ERROR
      - WARN
      - WARNING
      - INFO
      - DEBUG
      - TRACE
    Default value: INFO
  --no-color {single}
    Produce monochrome output. alias of --theme noColor.
  --theme <theme> {single}
    Choose color theme - default-force means colors will be produced even if
    command is piped.
    Possible values: 
      - default
      - default-force
      - noColor
    Default value: default
  --version {single}
    Print version information and quit.
  --quiet, -q {single}
    Quiet mode, doesn't display any output.


DESCRIPTION:
Lint awk files

Lint all files with .awk extension in current git folder.
Result in checkstyle format.

VERSION: 3.0

AUTHOR: [François Chastanet](https://github.com/fchastanet)

SOURCE FILE: https://github.com/fchastanet/bash-tools-framework/tree/master/src/_binaries/awkLint/awkLint-binary.yaml

LICENSE: MIT License
Copyright (c) 2022-now François Chastanet

3.5. bin/definitionLint

Lint binary definition files (YAML).

SYNOPSIS:
    Lint files of the given directory.

USAGE: definitionLint [OPTIONS] [ARGUMENTS]
USAGE: definitionLint [--format <format>] [--help|-h] [--config]
  [--bash-framework-config <bash-framework-config>] [--verbose|-v] [-vv] [-vvv]
  [--log-level <log-level>] [--log-file <log-file>]
  [--display-level <display-level>] [--no-color] [--theme <theme>] [--version]
  [--quiet|-q]

ARGUMENTS:
  folder {single} (mandatory)    the folder to recursively lint

OPTIONS:
  --format <format> {single}
    Define output format of this command.
    Possible values: 
      - plain
      - checkstyle
    Default value: plain

GLOBAL OPTIONS:
  --help, -h {single}
    Displays this command help
  --config {single}
    Displays configuration
  --bash-framework-config <bash-framework-config> {single}
    Use alternate bash framework configuration.
  --verbose, -v {single}
    Info level verbose mode (alias of --display-level INFO)
  -vv {single}
    Debug level verbose mode (alias of --display-level DEBUG)
  -vvv {single}
    Trace level verbose mode (alias of --display-level TRACE)
  --log-level <log-level> {single}
    Set log level
    Possible values: 
      - OFF
      - ERR
      - ERROR
      - WARN
      - WARNING
      - INFO
      - DEBUG
      - TRACE
    Default value: OFF
  --log-file <log-file> {single}
    Set log file
    Default value: /bash/bin/logs/definitionLint.log
  --display-level <display-level> {single}
    Set display level
    Possible values: 
      - OFF
      - ERR
      - ERROR
      - WARN
      - WARNING
      - INFO
      - DEBUG
      - TRACE
    Default value: INFO
  --no-color {single}
    Produce monochrome output. alias of --theme noColor.
  --theme <theme> {single}
    Choose color theme - default-force means colors will be produced even if
    command is piped.
    Possible values: 
      - default
      - default-force
      - noColor
    Default value: default
  --version {single}
    Print version information and quit.
  --quiet, -q {single}
    Quiet mode, doesn't display any output.


DESCRIPTION:

For each definition file:

- check that all mandatory methods are existing
  installScripts_<fileName>_helpDescription
  installScripts_<fileName>_helpVariables
  installScripts_<fileName>_listVariables
  installScripts_<fileName>_defaultVariables
  installScripts_<fileName>_checkVariables
  installScripts_<fileName>_fortunes
  installScripts_<fileName>_dependencies
  installScripts_<fileName>_breakOnConfigFailure
  installScripts_<fileName>_breakOnTestFailure
  installScripts_<fileName>_install
  installScripts_<fileName>_configure
  installScripts_<fileName>_test

- check if other definitions files functions are defined by currently
  linted definition file it would mean that another file has defined
  the same methods

- check if each dependency exists

INTERNAL

VERSION: 3.0

AUTHOR: [François Chastanet](https://github.com/fchastanet)

SOURCE FILE: https://github.com/fchastanet/bash-tools-framework/tree/master/src/_binaries/definitionLint/definitionLint-binary.yaml

LICENSE: MIT License
Copyright (c) 2023-now François Chastanet