Add argument splitting section to readme (#1230)
This commit is contained in:
parent
8c0bb3dde7
commit
5d223b113e
63
README.md
63
README.md
@ -1936,6 +1936,69 @@ echo bar
|
|||||||
bar
|
bar
|
||||||
```
|
```
|
||||||
|
|
||||||
|
### Avoiding Argument Splitting
|
||||||
|
|
||||||
|
Given this `justfile`:
|
||||||
|
|
||||||
|
```make
|
||||||
|
foo argument:
|
||||||
|
touch {{argument}}
|
||||||
|
```
|
||||||
|
|
||||||
|
The following command will create two files, `some` and `argument.txt`:
|
||||||
|
|
||||||
|
```sh
|
||||||
|
$ just foo "some argument.txt"
|
||||||
|
```
|
||||||
|
|
||||||
|
The users shell will parse `"some argument.txt`" as a single argument, but when `just` replaces `touch {{argument}}` with `touch some argument.txt`, the quotes are not preserved, and `touch` will receive two arguments.
|
||||||
|
|
||||||
|
There are a few ways to avoid this: quoting, positional arguments, and exported arguments.
|
||||||
|
|
||||||
|
#### Quoting
|
||||||
|
|
||||||
|
Quotes can be added around the `{{argument}}` interpolation:
|
||||||
|
|
||||||
|
```make
|
||||||
|
foo argument:
|
||||||
|
touch '{{argument}}'
|
||||||
|
```
|
||||||
|
|
||||||
|
This preserves `just`'s ability to catch variable name typos before running, for example if you were to write `{{argumant}}`, but will not do what you want if the value of `argument` contains single quotes.
|
||||||
|
|
||||||
|
#### Positional Arguments
|
||||||
|
|
||||||
|
The `positional-arguments` setting causes all arguments to be passed as positional arguments, allowing them to be accessed with `$1`, `$2`, …, and `$@`, which can be then double-quoted to avoid further splitting by the shell:
|
||||||
|
|
||||||
|
```make
|
||||||
|
set positional-arguments
|
||||||
|
|
||||||
|
foo argument:
|
||||||
|
touch "$1"
|
||||||
|
```
|
||||||
|
|
||||||
|
This defeats `just`'s ability to catch typos, for example if you type `$2`, but works for all possible values of `argument`, including those with double quotes.
|
||||||
|
|
||||||
|
#### Exported Arguments
|
||||||
|
|
||||||
|
All arguments are exported when the `export` setting is set:
|
||||||
|
|
||||||
|
```make
|
||||||
|
set export
|
||||||
|
|
||||||
|
foo argument:
|
||||||
|
touch "$argument"
|
||||||
|
```
|
||||||
|
|
||||||
|
Or individual arguments may be exported by prefixing them with `$`:
|
||||||
|
|
||||||
|
```make
|
||||||
|
foo $argument:
|
||||||
|
touch "$argument"
|
||||||
|
```
|
||||||
|
|
||||||
|
This defeats `just`'s ability to catch typos, for example if you type `$argumant`, but works for all possible values of `argument`, including those with double quotes.
|
||||||
|
|
||||||
Changelog
|
Changelog
|
||||||
---------
|
---------
|
||||||
|
|
||||||
|
Loading…
Reference in New Issue
Block a user