Utility to work with shell variables.
GPL-3.0 License
${VAR}
format.${VAR}
format.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
${VAR}
format.${VAR}
format../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
./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
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}
./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."
./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. |
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 usinganother variable $VAR3 .Continuation of the multi-line comment. |
./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}`
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 usinganother variable $VAR3
.
Continuation of the multi-line comment.
Default value: ${VAR3}
./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`
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 usinganother
variable $VAR3
.
Continuation of the multi-line comment.
Default value: ${VAR3}
Path: 1.sh
Paths: 1.sh
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.
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. |
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. |
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. |
composer install
composer lint
composer lint:fix
composer test
composer build
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
branchRepository created using https://getscaffold.dev/ project scaffold template