bash-funk - Spice up your Bash!

1. What is it?
2. Installation
   1. Using git
   2. Using subversion
   3. Using curl
   4. Using wget
   5. Portable on Windows
3. Usage
   1. Customization
   2. Directory-scoped Environment Variables and Aliases
   3. Efficiently navigating the filesystem
   4. Using bash-funk modules separately
4. Updating
5. License

What is it?

bash-funk is a collection of useful commands for Bash 3.2 or higher.

See the markdown files of the different Bash modules for detailed information about the provided commands:

• ansi - ANSI colored text output
• aws - query information about Amazon WebServices (AWS)
• compression - file compression
• crypto - encryption and checksums
• docker - Docker and Docker Swarm management
• filesystem - filesystem navigation and file operations
• git - working with GIT repositories
• math - mathematical operations
• memory - query RAM information
• misc - useful commands that did not yet made it into a separate module
• network - query network information
• openssl - generate certificates and CAs with OpenSSL
• os - query presence of commands and installed software packages
• performance - test CPU, disk and network performance
• processes - query process information or kill processes by parent PID or used TCP ports
• random - generate random strings
• ssh - SSH key management operations
• strings - String manipulations

An adaptive bash prompt is provided too:

All bash-funk commands have a descriptive online help:

The command -help shows a list of all available commands

Installation

Using Git

Execute:

git clone https://github.com/vegardit/bash-funk --branch main --single-branch ~/bash-funk

Using Subversion

Execute:

svn checkout https://github.com/vegardit/bash-funk/trunk ~/bash-funk

Using Curl

Execute:

mkdir ~/bash-funk && \
cd ~/bash-funk && \
curl -#L https://github.com/vegardit/bash-funk/tarball/main | tar -xzv --strip-components 1

Using wget

Execute:

mkdir ~/bash-funk && \
cd ~/bash-funk && \
wget -qO- --show-progress https://github.com/vegardit/bash-funk/tarball/main | tar -xzv --strip-components 1

Portable on Windows

For your convenience we created a simple bootstrap Windows batch file that sets up a portable Cygwin installation pre-configured with bash-funk.

For more details see https://github.com/vegardit/cygwin-portable-installer#install.

Usage

Once bash-funk is installed, it can be used by sourcing the bash-funk.sh script which will then load all modules.

$ source ~/bash-funk/bash-funk.sh

All bash-funk commands are prefixed with a - by default and support the --help option.

Bash completion for options is supported by all commands too, simply type a dash (-) and hit the [TAB] key twice.

Customization

The following environment variables can be set in ~/.bash_funk_rc to customize bash-funk's behavior. This file will be sourced automatically.

• BASH_FUNK_PREFIX - if specified, the names of all bash-funk commands will be prefixed with this value. Must only contain alphanumeric characters a-z, A-Z, 0-9) and underscore _.
• BASH_FUNK_DIRS_COLOR - ANSI color code to be used by the bash prompt to highlight directories, default is 94 which will be transformed to \e[94m
• BASH_FUNK_NO_EXPORT_FUNCTIONS - if set to any value bash-funk commands are not exported to sub-shells, thus will not be available in your own shell scripts.
• BASH_FUNK_NO_TWEAK_BASH - if set to any value bash-funk will not automatically invoke the -tweak-bash command when loading.
• BASH_FUNK_NO_PROMPT - if set to any value bash-funk will not install it's Bash prompt function.
• BASH_FUNK_PROMPT_PREFIX - text that shall be shown at the beginning of the Bash prompt, e.g. a stage identifier (DEV/TEST/PROD)
• BASH_FUNK_PROMPT_DATE - prompt escape sequence for the date section, default is \t, which displays current time. See http://tldp.org/HOWTO/Bash-Prompt-HOWTO/bash-prompt-escape-sequences.html
• BASH_FUNK_PROMPT_NO_JOBS - if set to any value the Bash prompt will not display the number of shell jobs.
• BASH_FUNK_PROMPT_NO_SCREENS - if set to any value the Bash prompt will not display the number of detached screen/tmux sessions
• BASH_FUNK_PROMPT_NO_TTY - if set to any value the Bash prompt will not display the current tty.
• BASH_FUNK_PROMPT_NO_KUBECTL - if set to any value the Bash prompt will not display kubectl's current context
• BASH_FUNK_PROMPT_NO_GIT - if set to any value the Bash prompt will not display GIT branch and modification information.
• BASH_FUNK_PROMPT_NO_SVN - if set to any value the Bash prompt will not display SVN branch and modification information.

Directory-scoped Environment Variables and Aliases

When changing into a directory, the bash-funk Bash prompt can automatically evaluate .bash_funk_dir_rc files found in the current directory or it's parent directories to set context-relevant environment variables.

This feature is disabled by default. To enable it, define the variable BASH_FUNK_PROMPT_DIRENV_AUTHORIZED_DIRS in ~/.bash_funk_rc as an Bash array containing fully qualified paths to trusted directories. Only .bash_funk_dir_rc files found in these directories will be evaluated for security reasons. The entries in BASH_FUNK_PROMPT_DIRENV_AUTHORIZED_DIRS may also expressed as a variant of glob patterns, where * will match one directory level and ** any directory level.

The .bash_funk_dir_rc are executed in a sub-shell, whose output is captured and parsed. All lines matching the pattern export <VARNAME>=<VALUE> or alias <VARNAME>=<VALUE> will then be executed via eval in the context of the current shell.

If multiple files named .bash_funk_dir_rc are found in the directory hierarchy (from the current directory up to /), they will be all evaluated starting with the file at the highest level (i.e. /).

Here is an example setup:

1. A file at /opt/projects/.bash_funk_dir_rc containing:

   #!/usr/bin/env bash
   echo "export JAVA_VERSION=1.8"
   echo "export MAVEN_VERSION=3.5"

2. A file at /opt/projects/project1/.bash_funk_dir_rc containing:

   #!/usr/bin/env bash
   
   # override JAVA_VERSION=1.8 from /opt/projects/.bash_funk_dir_rc
   echo "export JAVA_VERSION=9"

3. BASH_FUNK_PROMPT_DIRENV_TRUSTED_DIRS in ~/.bash_funk_rc, either explicit:

   BASH_FUNK_PROMPT_DIRENV_TRUSTED_DIRS=(
     "/opt/projects"
     "/opt/projects/project1"
     "/opt/projects/project2"
   )

   or with single-level pattern matching

   BASH_FUNK_PROMPT_DIRENV_TRUSTED_DIRS=(
     "/opt/projects/*"
   )

   or with multi-level pattern matching

   BASH_FUNK_PROMPT_DIRENV_TRUSTED_DIRS=(
     "/opt/**"
   )

4. If you now cd into /opt/projects/project1/ the environment variables JAVA_VERSION=9 and MAVEN_VERSION=3.5 are present.
5. If you go one level up to /opt/projects/, JAVA_VERSION=1.8 will be set.
6. If you go one level up to /opt, the environment variables JAVA_VERSION and MAVEN_VERSION will be unset.
7. If you comment out the first entry in BASH_FUNK_PROMPT_DIRENV_TRUSTED_DIRS in ~/.bash_funk_rc:

   BASH_FUNK_PROMPT_DIRENV_TRUSTED_DIRS=(
     #"/opt/projects"
     "/opt/projects/project1"
     "/opt/projects/project2"
   )

   and again cd into /opt/projects/project1/ only the environment variables JAVA_VERSION=9 will be present as the /opt/projects/.bash_funk_dir_rc is not evaluated anymore.

Efficiently navigating the filesystem

1. Navigating up the directory tree

   1. Navigating to the parent directory:

      [me@local /opt/projects/project1/src/main/java/com/acme] $ ..
      [me@local /opt/projects/project1/src/main/java/com] $
      

   2. Navigating to the parent's parent directory:

      [me@local /opt/projects/project1/src/main/java/com/acme] $ ...
      [me@local /opt/projects/project1/src/main/java] $
      

   3. Navigating up n-levels:

      [me@local /opt/projects/project1/src/main/java/com/acme] $ .. 5
      [me@local /opt/projects/project1] $
      

   4. Navigating up to a directory with a given name:

      [me@local /opt/projects/project1/src/main/java/com/acme] $ .. project1
      [me@local /opt/projects/project1] $
      

   Note: .. is an alias for the command -cd-up which you also can use, e.g. -cd-up 5

2. Navigating down the directory tree to a directory with a given name:

   [me@local /opt/projects/project1] $ ++ acme
   [me@local /opt/projects/project1/src/main/java/com/acme] $
   

   Note: ++ is an alias for -cd-down which you also can use, e.g. -cd-down acme

3. Navigating back in the directory history

   1. Navigate back to the last visited directory:

      [me@local /var/log/project1/mod1] $ cd /opt/projects/project1
      [me@local /opt/projects/project1] $ -
      [me@local /var/log/project1/mod1] $
      

   2. Navigate back to a directory with a given name:

      [me@local /var/log/project1/mod1] $ cd /opt/projects/project1
      [me@local /opt/projects/project1] $ cd /opt/projects/project2
      [me@local /opt/projects/project2] $ cd /var/log/project2/mod2
      [me@local /var/log/project2/mod2] $ -- mod1
      [me@local /var/log/project1/mod1] $
      

   3. Navigate back to the n-last visited directory:

      [me@local /var/log/project1/mod1] $ cd /opt/projects/project1
      [me@local /opt/projects/project1] $ cd /opt/projects/project2
      [me@local /opt/projects/project2] $ cd /var/log/project2/mod2
      [me@local /var/log/project2/mod2] $ -- 3
      [me@local /var/log/project1/mod1] $
      

   Note: -- is an alias for -cd-hist which you also can use, e.g. -cd-hist mod1

Using bash-funk modules separately

All bash-funk modules are self-containing. This means, if you are only interested in the commands provided by one module, you can also directly source that particular module located in the modules folder and do not use the bash-funk.sh loader script.

Updating

Once loaded, you can easily update your bash-funk installation to the latest code base by using the -update command:

-update -yr

or:

-update --yes --reload

License

All files are released under the Apache License 2.0.

Individual files contain the following tag instead of the full license text:

SPDX-License-Identifier: Apache-2.0

This enables machine processing of license information based on the SPDX License Identifiers that are available here: https://spdx.org/licenses/.