Utility to work with shell variables

---

Features

• 🔎 Lint variables:
  • Report shell variables that are not in ${VAR} format.
  • Fix shell variables that are not in ${VAR} format.
  • Skip lines or blocks marked with # shellvar-ignore-* directives.
• 📋 Extract variables:
  • Scan a file or a directory containing shell scripts and extract found variables with comments and assigned values with advanced interpolation support.
  • Filter variables: exclude local, exclude by prefix, exclude from a list in a file.
  • Format output as CSV, a Markdown table or Markdown blocks (defined in a template).
  • Reorder, select or exclude columns in tabular output.

Installation

Download the latest version of shellvar from the releases page and run it on the host machine:

./shellvar [command] [options] path/to/script.sh

or run it as a Docker container:

docker run -v $(pwd):/app drevops/shellvar [command] [options] path/to/script.sh

Usage - Lint

• Report shell variables that are not in ${VAR} format.
• Fix shell variables that are not in ${VAR} format.

The command exits with a non-zero code when it reports at least 1 variable, so it can gate a CI job.

Lint file or directory

./shellvar lint path/to/script.sh

./shellvar lint path/to/dir

./shellvar lint --extension=sh --extension=bash --extension=bats \
  path/to/dir

Directories are scanned recursively for files with the given extensions.

Fix file or directory

./shellvar lint --fix path/to/script.sh

./shellvar lint --fix path/to/dir

./shellvar lint --fix --extension=sh --extension=bash --extension=bats \
  path/to/dir

Ignore lines

Use comment directives to skip a single line or a block of lines:

# shellvar-ignore-next-line
var=$VAR1

# shellvar-ignore-start
var=$VAR2
var=$VAR3
# shellvar-ignore-end

Lint options

Name	Description	Default value
path	File or directory to check.
-e, --extension=EXTENSION	File extension to filter by when path is a directory. Multiple values allowed.	sh, bash
-f, --fix	Fixes the variables in the file instead of reporting them.

Usage - Extract

By default, variable names, descriptions (taken from the comments) and their values are printed to STDOUT in the CSV format. You can also change the output format to Markdown table or Markdown blocks.

Given the following shell script (see the extended example used in tests):

# Assignment to scalar value.
VAR1=val1
# Assignment to another variable.
VAR2="${VAR1}"
# Parameter expansion.
VAR3=${val3:-abc}
# Parameter expansion with a default value using
# another variable $VAR3.
#
# Continuation of the multi-line comment.
VAR4=${val4:-$VAR3}

CSV (default)

./shellvar extract path/to/script.sh

Name;"Default value";Description
VAR1;val1;"Assignment to scalar value."
VAR2;${VAR1};"Assignment to another variable."
VAR3;abc;"Parameter expansion."
VAR4;${VAR3};"Parameter expansion with a default value using another variable $VAR3.

Continuation of the multi-line comment."

Markdown table

./shellvar extract --format=md-table path/to/script.sh

Click to see output

| Name   | Default value | Description                                                                                                               |
|--------|---------------|---------------------------------------------------------------------------------------------------------------------------|
| `VAR1` | `val1`        | Assignment to scalar value.                                                                                               |
| `VAR2` | `${VAR1}`     | Assignment to another variable.                                                                                           |
| `VAR3` | `abc`         | Parameter expansion.                                                                                                      |
| `VAR4` | `${VAR3}`     | Parameter expansion with a default value using another variable `$VAR3`.<br/><br/>Continuation of the multi-line comment. |

which renders as

Name	Default value	Description
VAR1	val1	Assignment to scalar value.
VAR2	${VAR1}	Assignment to another variable.
VAR3	abc	Parameter expansion.
VAR4	${VAR3}	Parameter expansion with a default value using another variable $VAR3. Continuation of the multi-line comment.

Markdown blocks

./shellvar extract --format=md-blocks path/to/script.sh

Click to see output

### `VAR1`

Assignment to scalar value.

Default value: `val1`

### `VAR2`

Assignment to another variable.

Default value: `${VAR1}`

### `VAR3`

Parameter expansion.

Default value: `abc`

### `VAR4`

Parameter expansion with a default value using<br/>another variable `$VAR3`.

Continuation of the multi-line comment.

Default value: `${VAR3}`

which renders as

VAR1 Assignment to scalar value. Default value: val1 VAR2 Assignment to another variable. Default value: ${VAR1} VAR3 Parameter expansion. Default value: abc VAR4 Parameter expansion with a default value using another variable $VAR3. Continuation of the multi-line comment. Default value: ${VAR3}

Advanced: Markdown blocks with links and custom template

Given a template file template.md:

### {{ name }}

{{ description }}

Default value: {{ default_value }}

Path: {{ path }}

Paths: {{ paths }}

and the preceding script saved as 1.sh in the current directory:

./shellvar extract \
  --format=md-blocks \
  --md-link-vars \
  --md-block-template-file=template.md \
  --path-strip-prefix="${PWD}/" \
  1.sh

Click to see output

### `VAR1`

Assignment to scalar value.

Default value: `val1`

Path: `1.sh`

Paths: `1.sh`

### `VAR2`

Assignment to another variable.

Default value: `${VAR1}`

Path: `1.sh`

Paths: `1.sh`

### `VAR3`

Parameter expansion.

Default value: `abc`

Path: `1.sh`

Paths: `1.sh`

### `VAR4`

Parameter expansion with a default value using<br/>another variable [`$VAR3`](#VAR3).

Continuation of the multi-line comment.

Default value: `${VAR3}`

Path: `1.sh`

Paths: `1.sh`

which renders as

VAR1 Assignment to scalar value. Default value: val1 Path: 1.sh Paths: 1.sh VAR2 Assignment to another variable. Default value: ${VAR1} Path: 1.sh Paths: 1.sh VAR3 Parameter expansion. Default value: abc Path: 1.sh Paths: 1.sh VAR4 Parameter expansion with a default value using another variable $VAR3. Continuation of the multi-line comment. Default value: ${VAR3} Path: 1.sh Paths: 1.sh

Column manipulation

Control the order and visibility of columns in tabular output formats (CSV and Markdown table).

Reorder columns

./shellvar extract --format=csv \
  --column-order="Description,Name" \
  path/to/script.sh

This outputs columns in the order: Description, Name, Default value (unspecified columns are appended).

Show only specific columns

./shellvar extract --format=md-table \
  --only-columns="Name,Description" \
  path/to/script.sh

This outputs only the Name and Description columns.

Exclude columns

./shellvar extract --format=csv \
  --exclude-columns="Default value" \
  path/to/script.sh

This outputs all columns except "Default value".

Combine column options

./shellvar extract --format=csv \
  --only-columns="Name,Description,Default value" \
  --column-order="Description,Name" \
  path/to/script.sh

This first filters to only the specified columns, then reorders them.

Options

There are options for different phases: extraction, filtering and formatting.

"Multiple values allowed" means that you can specify the option multiple times like so: --exclude-prefix=VAR1 --exclude-prefix=VAR2 etc.

Extraction

Name	Description	Default value
paths	File or directory to scan. Multiple paths separated by space. Directories are scanned non-recursively for .env, *.sh and *.bash files, including hidden ones.
--skip-text=SKIP	Skip variable extraction if the comment has this specified text.	@skip
--skip-description-prefix=PREFIX	Skip description lines that start with the provided prefix. Multiple values allowed.

Filtering

Name	Description	Default value
--exclude-local	Remove local variables.
--exclude-prefix=PREFIX	Exclude variables that start with the provided prefix. Multiple values allowed.
--exclude-from-file=FILE	A path to a file that contains variables to be excluded from the extraction process. Multiple values allowed.

Format

Name	Description	Default value
--format=FORMAT	The output format: CSV (csv), Markdown table (md-table), Markdown blocks (md-blocks).	csv
--sort	Sort variables in ascending order by name.
--unset	A string to represent a value for variables that are defined but have no set value.	UNSET
--fields=FIELDS	Semicolon-separated list of fields. Each field is a key-label pair in the format "key=label". If label is omitted, key is used as label.	name=Name;default_value="Default value";description=Description
--path-strip-prefix=PREFIX	Strip the provided prefix from the path.
--csv-separator=SEPARATOR	Separator for the CSV output format.	;
--column-order=COLUMNS	Comma-separated list of column names to specify output order. Columns not specified are appended in their original order. Only applies to tabular formats (csv, md-table).
--only-columns=COLUMNS	Comma-separated list of column names to include. Only these columns will appear in output. Only applies to tabular formats (csv, md-table).
--exclude-columns=COLUMNS	Comma-separated list of column names to exclude from output. Only applies to tabular formats (csv, md-table).
--md-link-vars	Link variables within usages to their definitions in the Markdown output format.
--md-link-vars-anchor-case	The case of the anchors when linking variables. Can be one of "preserve", "lower" or "upper".	preserve
--md-no-inline-code-wrap-vars	Do not wrap variables to show them as inline code in the Markdown output format.
--md-no-inline-code-wrap-numbers	Do not wrap numbers to show them as inline code in the Markdown output format.
--md-inline-code-extra-file=FILE	A path to a file that contains additional strings to be formatted as inline code in the Markdown output format. Multiple values allowed.
--md-block-template-file=FILE	A path to a Markdown template file used for Markdown blocks (md-blocks) output format. {{ name }}, {{ description }}, {{ default_value }}, {{ path }} and {{ paths }} tokens can be used within the template.

Contributing

CONTRIBUTING.md covers local development setup, the lint and test commands and how the Docker image is published.

---

This repository was created using the Scaffold project template