drevops/shellvar repository overview

⁠

⁠Utility to work with shell variables

⁠Features

• Lint variables:
  • Report on shell variables that are not in ${VAR} format.
  • Fix shell variables that are not in ${VAR} format.
• 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 file.
  • Format output as a CSV, Markdown table or Markdown blocks (defined in the template).
  • Extend filters and formatters with your own custom classes.

⁠Installation

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

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

or run as a Docker container:

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

⁠Usage - Lint

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

⁠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

Example:

./shellvar lint tests/phpunit/Fixtures/unwrapped.sh

./shellvar lint tests/phpunit/Fixtures

./shellvar lint --extension=sh --extension=bash --extension=bats tests/phpunit/Fixtures

⁠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

Example:

./shellvar lint --fix tests/phpunit/Fixtures/unwrapped.sh

./shellvar lint --fix tests/phpunit/Fixtures

./shellvar lint --fix --extension=sh --extension=bash --extension=bats tests/phpunit/Fixtures

⁠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 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

| 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<br/>another variable `$VAR3`.<br/><br/>Continuation of the multi-line comment. |

⁠Markdown blocks

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

### `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}`

⁠Advanced: Markdown blocks with links and custom template

./shellvar extract --format=md-blocks --md-link-vars --md-block-template-file=path/to/template.md path/to/script.sh

### `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`

⁠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 will output 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 will output only the Name and Description columns.

⁠Exclude columns

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

This will output 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 will first filter to only the specified columns, then reorder 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

⁠Filtering

⁠Format

⁠Maintenance

composer install
composer lint
composer lint:fix
composer test
composer build

⁠Docker publishing

Shellvar is published as a Docker image⁠ with the following tags:

• XX.YY.ZZ tag - when release tag is published on GitHub.
• latest - when release tag is published on GitHub.
• canary - on every push to main branch

This repository was created using the Scaffold⁠ project template