90 lines
2.7 KiB
Markdown
90 lines
2.7 KiB
Markdown
## available environment variables
|
|
|
|
- `PROJECT_ROOT` is the root directory of your project, the one
|
|
with files that need to be reformatted. Currently (as of 2023-09) this is
|
|
just the output of `git rev-parse --show-toplevel` but it may be improved.
|
|
- `WF_ROOT` is the root directory of the `would-format` checkout
|
|
|
|
file checking and sniffing
|
|
|
|
## file type sniffing
|
|
|
|
You can override a file type by creating an executable in
|
|
`$WOULD_FORMAT_PROJECT_ROOT/.would-format/sniffer`. This is typically a shell
|
|
script, but it doesn't have to be. It takes one argument, the full path of
|
|
the file to be checked.
|
|
|
|
This file should print the type of file it should be treated as. If the
|
|
script has no opinion on the matter, it should print nothing and exit. Here
|
|
is an example:
|
|
|
|
```shell-script
|
|
#!/usr/bin/env bash
|
|
|
|
file="$1"
|
|
|
|
if [[ $file == *.pl ]] ; then
|
|
# the default is that .pl corresponds to perl, but not here!
|
|
echo -n "prolog"
|
|
fi
|
|
|
|
if [[ $file == *.ts ]] ; then
|
|
# qt translations, who knew
|
|
echo -n "qt-translation"
|
|
fi
|
|
|
|
# We're fine with the defaults for other types of files so we don't
|
|
# print anything else.
|
|
|
|
exit 0
|
|
```
|
|
|
|
Return values:
|
|
|
|
- 0: success
|
|
- 254: file can't be read due to permissions, etc ("etc" is as of
|
|
2023-Q3 broad in scope; it could include trying and failing to read a file
|
|
on a NFS mount)
|
|
- 255: some sort of internal error
|
|
|
|
|
|
|
|
|
|
## return value normalization for formatters
|
|
|
|
In general, low-numbered codes are related to the code to be analyzed
|
|
or reformatted and high-numbered codes have to do with problems with these
|
|
scripts themselves.
|
|
|
|
### In `would_format` mode
|
|
|
|
`would-format.sh` interprets return values to mean the following:
|
|
|
|
FIXME: Unsurprisingly, `gofmt` gets this right, even if none of the other
|
|
tools does. Drop `1`.
|
|
|
|
- 0: file wouldn't be reformatted
|
|
- 1: file would be reformatted
|
|
- 2: file has at least one syntax error
|
|
- 252: Unexpected return value from the tool; that is, the value of `$?` is
|
|
unexpected and thus unhandled
|
|
- 253: Unexpected output from the tool; that is, the output emitted by the
|
|
tool is unexpected and thus unhandled
|
|
- 254: file can't be read due to permissions, etc ("etc" is as of
|
|
2023-Q3 broad in scope; it could include trying and failing to read a file
|
|
on a NFS mount)
|
|
- 255: error internal to the script in question
|
|
|
|
|
|
# in `do_format` mode
|
|
|
|
`do-format.sh` interprets return values to mean the following:
|
|
|
|
- 0: file was successfully reformatted
|
|
- 1: file was not successfully reformatted, presumably due to a syntax error
|
|
- 254: file can't be rewritten due to permissions, etc ("etc" is as of
|
|
2023-Q3 broad in scope; it could include trying and failing to read a file
|
|
on a NFS mount)
|
|
- 255: error internal to the script in question
|
|
|