# Settings

Some of bashly's commands can be tweaked through the use of environment variables, or a settings file.

If you wish to load settings from a configuration file, you can generate an initial settings file by running:

$ bashly add settings

which will create the default settings.yml file in the working directory.

Bashly will look for the settings file in one of these paths:

• A path set in the environment variable BASHLY_SETTINGS_PATH.
• A file named bashly-settings.yml in the working directory.
• A file named settings.yml in the working directory.

Settings Example

All settings are optional (with their default values provided below), and can also be set with an environment variable with the same name, capitalized and prefixed by BASHLY_ - for example: BASHLY_SOURCE_DIR

When setting environment variables, you can use:

• 0, false or no to represent false
• 1, true or yes to represent true

# default
source_dir: src

Set the path containing the bashly source files.

# default
config_path: "%{source_dir}/bashly.yml"

Set the path to bashly.yml. You can use the special token %{source_dir} to reference the value of the source_dir option.

# default
target_dir: .

Set the path to use for creating the final bash script.

# default
lib_dir: lib

Set the path to use for common library files, relative to source_dir.

# default
commands_dir: ~

# example
commands_dir: commands

Set the path to use for command files, relative to source_dir.

• When set to nil (denoted by ~), command files will be placed directly under source_dir.
• When set to any other string, command files will be placed under this directory, and each command will get its own sub-directory.

In case you plan on creating a large script with many commands, it is recommended to enable this by setting it to something like commands_dir: commands.

Command Paths Example

# default
partials_extension: sh

# example
partials_extension: bash

Set the extension to use when reading/writing partial script snippets.

# default
strict: false

# examples
strict: true
strict: ''
strict: set -o pipefail

Specify which bash options to apply on initialization.

• strict: true - Bash strict mode (set -euo pipefail)
• strict: false - Only exit on errors (set -e)
• strict: '' - Do not add any set directive
• strict: <string> - Add any other custom set directive, for example strict: set -o pipefail

# default
tab_indent: false

Specify the indentation style of the generated script.

• tab_indent: false - Indent with two spaces.
• tab_indent: true - Indent with Tab (every 2 leading spaces will be converted to a tab character).

# default
compact_short_flags: true

Specify how the generated script should treat flags in the form of -abc

• compact_short_flags: true - Expand -abc to -a -b -c.
• compact_short_flags: false - Do not expand -abc (consider this an invalid input).

# default
conjoined_flag_args: true

Specify how the generated script should treat flags in the form of --flag=value or -f=value

• conjoined_flag_args: true - Expand --flag=value to --flag value and -f=value to -f value.
• conjoined_flag_args: false - Do not expand --flag=value or -f=value (consider this an invalid input).

# default
show_examples_on_error: false

Specify if you want to show the command examples whenever the user fails to provide the required arguments.

Show Examples on Error Example

# default
private_reveal_key: ~

# example
private_reveal_key: ADVANCED_FEATURES

When using private commands, flags, or environment variables, you may set this option to a name of an environment variable that, if set, will reveal all the private elements in the usage texts, as if they were public.

Private Reveal Example

# default
usage_colors:
  caption: ~
  command: ~
  arg: ~
  flag: ~
  environment_variable: ~

# example
usage_colors:
  caption: bold
  command: green_underlined
  arg: blue
  flag: magenta
  environment_variable: cyan_bold

Enable color output for several aspects of the help message of the generated script. Each of these options may be a name of a color function that exists in your script, for example: green or bold.

You can run bashly add colors to add a standard colors library.

Usage Colors Example

# default
env: development

Specify one of two script rendering environments:

• env: development - Generate a script suitable for development, which is usually slightly larger and contains additional development-specific features.
• env: production - Generate a script suitable for distribution, which is usually smaller.

Use the enable_* options below to adjust settings for each environment.

# default (allowed: always, never, development, production)
enable_header_comment: always

Specify if you wish to render the "do not modify" comment at the beginning of the script.

# default (allowed: always, never, development, production)
enable_bash3_bouncer: always

Specify if you wish to render the piece of code that aborts the script execution when bash version is < 4.

# default (allowed: always, never, development, production)
enable_view_markers: development

Specify if you want the rendered script to include view marker comments.

View markers provide the name of the internal bashly template (view) or the path to the user's partial code files in the final script, to help locate the source file for each piece of code.

# default (allowed: always, never, development, production)
enable_inspect_args: development

Specify if you want the rendered script to include the inspect_args() function.

The inspect_args() function can help in reviewing the input for each command.

# default (allowed: always, never, development, production)
enable_deps_array: always

Specify if you want to populate the $deps bash array.

This is applicable only if your script uses the Dependency configuration option.

# default (allowed: always, never, development, production)
enable_env_var_names_array: always

Specify if you want to populate the $env_var_names bash array.

This is applicable only if your script uses the Environment Variable configuration option.

# default (allowed: always, never, development, production)
enable_sourcing: development

Specify if you want the generated script to include a condition that checks if the script was sourced and only execute it if it is not.

# default
var_aliases:
  args: ~
  other_args: ~
  deps: ~
  env_var_names: ~

# example
var_aliases:
  args: ARGS
  other_args: catch_all
  deps: dependencies
  env_var_names: ENV_VARS

Update one or more of these options in case you wish to change the name of the public global array that bashly uses for storing data.

Note that this feature will not change the original name, but rather create an alias using declare -gn.