# Custom Libraries Source

Bashly is capable of importing library functions from a custom external source (not built into Bashly itself) using the bashly add --source NAME ... command.

A libraries source can be:

1. A local path
2. A remote git repository
3. A remote GitHub repository (public or private)

This can be useful if:

1. You have multiple bashly-generated scripts, and wish to have a central place for shareable libraries.
2. You wish to create a public source for libraries for bashly.
3. You wish to create a private shareable libraries source for your organization.

The external libraries source must have a libraries.yml file in its root directory describing the libraries it provides. A typical libraries.yml file looks like this:

colors:
  help: Add standard functions for printing colorful text.
  files:
    - source: "colors/colors.sh"
      target: "%{user_lib_dir}/colors.%{user_ext}"

config:
  help: Add standard functions for handling INI files.
  files:
    - source: "config/config.sh"
      target: "%{user_lib_dir}/config.%{user_ext}"

  post_install_message: |
    Remember to set up the CONFIG_FILE variable in your script.
    For example: CONFIG_FILE=settings.ini.

String Required

The message to show when running bashly add --source NAME --list

Array of Dictionaries Required

An array of source + target paths of files to copy when adding this library.

• source is relative to the root of the libraries source.
• target is relative to the current directory, and you can use any of these tokens in the path:
  • %{user_source_dir} - path to the user's source directory (normally ./src).
  • %{user_target_dir} - path to the user's target directory (normally .).
  • %{user_lib_dir} - path to the user's lib directory (normally ./src/lib).
  • %{user_ext} - the user's selected partials extension (normally sh).

String

An optional message to show after the user installs the library. You can use a multi-line YAML string here, and use color markers as specified by the Colsole gem (already bundled with Bashly).

In the below example, g`...` means green, m`...` magenta, and bu`...` blue underlined:

post_install_message: |
  Edit your tests in g`test/approve` and then run:

    m`$ test/approve`

  Docs: bu`https://github.com/DannyBen/approvals.bash`

Boolean

Set skip_src_check: true if your library’s target files are not meant to be placed in the user's src directory.

This disables the automatic check for the existence of that directory during installation.

You are free to split or group functions in your custom library however it makes sense for your project.

If several functions work together on the same concern, you can keep them in a single file.

Example: config library

If functions are unrelated, you can place each in its own file (and even in subdirectories).

Example: validations library

When you run bashly generate, Bashly automatically includes every .sh file in your library folder (including subdirectories). This is what makes both styles possible.

Your library files can be set to auto-upgrade when running bashly generate --upgrade. In order to enable this functionality, you need to add a special upgrade marker to your file:

## [@bashly-upgrade source-uri;library-name]

For example

## [@bashly-upgrade github:you/your-repo;config]

You can also use the shorthand version of the marker, which will be replaced with the full marker when the library is added:

## [@bashly-upgrade]

The ## marker is recommended since it creates a hidden comment that will not appear in the final generated bash script.

If you prefer the marker to remain visible, you may use a single # instead.