Skip to content

Utility to work with shell variables.

License

Notifications You must be signed in to change notification settings

AlexSkrypnyk/shellvar

Repository files navigation

Shellvar logo

Utility to work with shell variables

GitHub Issues GitHub Pull Requests Test PHP codecov GitHub release (latest by date) LICENSE Renovate

Docker Pulls amd64


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
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<br />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

./shellvar extract --format=md-blocks --md-link-vars --md-block-template-file=path/to/template.md path/to/script.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

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 files separated by space.
--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. ;
--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 }} and {{ path }} tokens can be used within the template.

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

Repository created using https://getscaffold.dev/ project scaffold template