would-reformat/NEW-FORMATTERS.md

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:

#!/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