Skip to content

Commit 3726cb0

Browse files
bradykiefferbradykieffer
authored
chore: document the config option (#51)
Related: tconbeer/sqlfmt#698
1 parent d089074 commit 3726cb0

1 file changed

Lines changed: 22 additions & 21 deletions

File tree

‎docs/getting-started/configuring-sqlfmt.md‎

Lines changed: 22 additions & 21 deletions
Original file line numberDiff line numberDiff line change
@@ -69,28 +69,29 @@ If you have `NO_COLOR` set (for other programs) and want sqlfmt to colorize outp
6969
use the force-color option, via `--force-color`, `SQLFMT_FORCE_COLOR`, or `force_color=true`
7070
in your `pyproject.toml` file.
7171

72-
If the force-color option is set, sqlfmt will colorize output, no matter how no-color and
72+
If the force-color option is set, sqlfmt will colorize output, no matter how no-color and
7373
force-color are set. For example, if `force_color=true` is set in the config file, but
74-
sqlfmt is run with the `--no-color` option, it **will** colorize output.
74+
sqlfmt is run with the `--no-color` option, it **will** colorize output.
7575

7676
## Configuration Reference
7777

78-
| CLI Option | Environment Variable | Config File | Description |
79-
|------------------------------------------|--------------------------------------|---------------------------------|----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------|
80-
| `--help` | ❌ | ❌ | Show the help message and exit. |
81-
| `--version` | ❌ | ❌ | Show the version and exit. |
82-
| `--check` | `SQLFMT_CHECK=1` | `check=true` | Fail with an exit code of 1 if source files are not formatted to spec. Do not write formatted queries to files. |
83-
| `--diff` | `SQLFMT_DIFF=1` | `diff=true` | Print a diff of any formatting changes to stdout. Fails like `--check` on any changes. Do not write formatted queries to files. |
84-
| `-l 99`, `--line-length 99` | `SQLFMT_LINE_LENGTH=99` | `line_length=99` | The maximum line length allowed in output files. Default is 88. |
85-
| `--exclude ./my_dir/**/*.sql` | `SQLFMT_EXCLUDE="./my_dir/**/*.sql"` | `exclude=["./my_dir/**/*.sql"]` | A string that is passed to glob.glob as a pathname; any matching files returned by glob will be excluded from FILES and not formatted. Note that glob is relative to the current working directory when sqlfmt is called. To exclude multiple globs, repeat the `--exclude` option. The TOML file takes a list of strings. |
86-
| `--encoding inherit` | `SQLFMT_ENCODING=inherit` | `encoding="inherit"` | The encoding to use when reading and writing .sql files. Defaults to utf-8. Set to 'inherit' to read the system default encoding. utf encodings will detect and preserve the BOM if one is present. |
87-
| `-d clickhouse`, `--dialect clickhouse` | `SQLFMT_DIALECT=clickhouse` | `dialect="clickhouse"` | The SQL dialect for the target files. Nearly all dialects are supported by the default polyglot dialect. Select the ClickHouse dialect to respect case sensitivity in function, field, and alias names. |
88-
| `--no-jinjafmt` | `SQLFMT_NO_JINJAFMT=1` | `no_jinjafmt=true` | Do not format Jinja tags (the code between the curlies). Only necessary to specify this flag if sqlfmt was installed with the jinjafmt extra, or if *Black* was already available in this environment. |
89-
| `--fast`, `--safe` | `SQLFMT_FAST=1` | `fast=true` | By default, sqlfmt re-processes the output it produces in order to run a safety check and ensure that all tokens from the input are present in the output. This can add 15-20% to the processing time for new files. To disable this safety check, use the `--fast` option. To force the safety check, use `--safe`." |
90-
| `-k`, `--reset-cache` | `SQLFMT_RESET_CACHE=1` | `reset_cache=true` | Clear the sqlfmt cache before running, effectively forcing sqlfmt to operate on every file. Will slow down runs. |
91-
| `-v`, `--verbose` | `SQLFMT_VERBOSE=1` | `verbose=true` | Prints more information to stderr. |
92-
| `-q`, `--quiet` | `SQLFMT_QUIET=1` | `quiet=true` | Prints much less information to stderr. |
93-
| `--no-color` | `NO_COLOR=1`, `SQLFMT_NO_COLOR=1` | `no_color=true` | Removes color codes from all output, including diffs. See https://no-color.org/ for more details. |
94-
| `--force-color` | `SQLFMT_FORCE_COLOR=1` | `force_color=true` | sqlfmt output is colorized by default. However, if you have the `NO_COLOR` env var set, and still want sqlfmt to colorize output, you can use `--force-color` to override the no-color option. |
95-
| `--no-progressbar` | `SQLFMT_NO_PROGRESSBAR=1` | `no_progressbar=true` | Never prints a progressbar to stderr. |
96-
| `--single-process` | `SQLFMT_SINGLE_PROCESS=1` | `single_process=true` | Run sqlfmt in a single process, even when formatting multiple files. If not set, defaults to multiprocessing using as many cores as possible. Also disables the progress bar. Will slow down runs. |
78+
| CLI Option | Environment Variable | Config File | Description |
79+
|------------------------------------------|-----------------------------------------|---------------------------------|----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------|
80+
| `--help` | ❌ | ❌ | Show the help message and exit. |
81+
| `--version` | ❌ | ❌ | Show the version and exit. |
82+
| `--check` | `SQLFMT_CHECK=1` | `check=true` | Fail with an exit code of 1 if source files are not formatted to spec. Do not write formatted queries to files. |
83+
| `--diff` | `SQLFMT_DIFF=1` | `diff=true` | Print a diff of any formatting changes to stdout. Fails like `--check` on any changes. Do not write formatted queries to files. |
84+
| `-l 99`, `--line-length 99` | `SQLFMT_LINE_LENGTH=99` | `line_length=99` | The maximum line length allowed in output files. Default is 88. |
85+
| `--exclude ./my_dir/**/*.sql` | `SQLFMT_EXCLUDE="./my_dir/**/*.sql"` | `exclude=["./my_dir/**/*.sql"]` | A string that is passed to glob.glob as a pathname; any matching files returned by glob will be excluded from FILES and not formatted. Note that glob is relative to the current working directory when sqlfmt is called. To exclude multiple globs, repeat the `--exclude` option. The TOML file takes a list of strings. |
86+
| `--encoding inherit` | `SQLFMT_ENCODING=inherit` | `encoding="inherit"` | The encoding to use when reading and writing .sql files. Defaults to utf-8. Set to 'inherit' to read the system default encoding. utf encodings will detect and preserve the BOM if one is present. |
87+
| `-d clickhouse`, `--dialect clickhouse` | `SQLFMT_DIALECT=clickhouse` | `dialect="clickhouse"` | The SQL dialect for the target files. Nearly all dialects are supported by the default polyglot dialect. Select the ClickHouse dialect to respect case sensitivity in function, field, and alias names. |
88+
| `--no-jinjafmt` | `SQLFMT_NO_JINJAFMT=1` | `no_jinjafmt=true` | Do not format Jinja tags (the code between the curlies). Only necessary to specify this flag if sqlfmt was installed with the jinjafmt extra, or if *Black* was already available in this environment. |
89+
| `--fast`, `--safe` | `SQLFMT_FAST=1` | `fast=true` | By default, sqlfmt re-processes the output it produces in order to run a safety check and ensure that all tokens from the input are present in the output. This can add 15-20% to the processing time for new files. To disable this safety check, use the `--fast` option. To force the safety check, use `--safe`." |
90+
| `-k`, `--reset-cache` | `SQLFMT_RESET_CACHE=1` | `reset_cache=true` | Clear the sqlfmt cache before running, effectively forcing sqlfmt to operate on every file. Will slow down runs. |
91+
| `-v`, `--verbose` | `SQLFMT_VERBOSE=1` | `verbose=true` | Prints more information to stderr. |
92+
| `-q`, `--quiet` | `SQLFMT_QUIET=1` | `quiet=true` | Prints much less information to stderr. |
93+
| `--no-color` | `NO_COLOR=1`, `SQLFMT_NO_COLOR=1` | `no_color=true` | Removes color codes from all output, including diffs. See https://no-color.org/ for more details. |
94+
| `--force-color` | `SQLFMT_FORCE_COLOR=1` | `force_color=true` | sqlfmt output is colorized by default. However, if you have the `NO_COLOR` env var set, and still want sqlfmt to colorize output, you can use `--force-color` to override the no-color option. |
95+
| `--no-progressbar` | `SQLFMT_NO_PROGRESSBAR=1` | `no_progressbar=true` | Never prints a progressbar to stderr. |
96+
| `--single-process` | `SQLFMT_SINGLE_PROCESS=1` | `single_process=true` | Run sqlfmt in a single process, even when formatting multiple files. If not set, defaults to multiprocessing using as many cores as possible. Also disables the progress bar. Will slow down runs. |
97+
| `--config` | `SQLFMT_CONFIG=/path/to/pyproject.toml` | ❌ | Provide sqlfmt with a configuration file directly. If not set, sqlfmt will attempt to find a configuration file automatically. Other options passed at the command line will override settings in this file. Must exist or an exception will be thrown. |

0 commit comments

Comments
 (0)