Skip to content

Commit

Permalink
docs: update for v0.13 features, clean up config table (tconbeer#9)
Browse files Browse the repository at this point in the history 
* docs: update for v0.13 features, clean up config table

* feat: add link to config reference
  • Loading branch information
@tconbeer
tconbeer authored Nov 1, 2022
1 parent 6172d97 commit d0adf11
Show file tree
Hide file tree
Showing 3 changed files with 21 additions and 21 deletions.
36 changes: 18 additions & 18 deletions docs/getting-started/configuring-sqlfmt.md
View file
Original file line number Diff line number Diff line change
Expand Up @@ -18,7 +18,7 @@ sqlfmt -l 99 .

## Configuring Operations

sqlfmt's operation, however, is highly configurable using options at the command line. For a full list of options, see below, or type:
sqlfmt's operation, however, is highly configurable using options at the command line. For a full list of options, see [below](#configuration-reference), or type:

```bash
sqlfmt --help
Expand Down Expand Up @@ -75,20 +75,20 @@ sqlfmt is run with the `--no-color` option, it **will** colorize output.

## Configuration Reference

| CLI Option | Environment Variable | Config File | Description |
|------------------------------------------|--------------------------------------|---------------------------------|-----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------|
| `--help` | ❌ | ❌ | Show the help message and exit |
| `--version` | ❌ | ❌ | Show the version and exit. |
| `--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. |
| `--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. |
| `--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. |
| `--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. |
| `-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. |
| `--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. |
| `-l 99`, `--line-length 99` | `SQLFMT_LINE_LENGTH=99` | `line_length=99` | The maximum line length allowed in output files. Default is 88. |
| `-v`, `--verbose` | `SQLFMT_VERBOSE=1` | `verbose=true` | Prints more information to stderr. |
| `-q`, `--quiet` | `SQLFMT_QUIET=1` | `quiet=true` | Prints much less information to stderr. |
| `--no-progressbar` | `SQLFMT_NO_PROGRESSBAR=1` | `no_progressbar=true` | Never prints a progressbar to stderr. |
| `--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. |
| `--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. |
| `-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. |
| CLI Option | Environment Variable | Config File | Description |
|------------------------------------------|--------------------------------------|---------------------------------|----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------|
| `--help` | ❌ | ❌ | Show the help message and exit |
| `--version` | ❌ | ❌ | Show the version and exit. |
| `--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. |
| `--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. |
| `-l 99`, `--line-length 99` | `SQLFMT_LINE_LENGTH=99` | `line_length=99` | The maximum line length allowed in output files. Default is 88. |
| `--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. |
| `-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. |
| `--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. |
| `-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. |
| `-v`, `--verbose` | `SQLFMT_VERBOSE=1` | `verbose=true` | Prints more information to stderr. |
| `-q`, `--quiet` | `SQLFMT_QUIET=1` | `quiet=true` | Prints much less information to stderr. |
| `--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. |
| `--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. |
| `--no-progressbar` | `SQLFMT_NO_PROGRESSBAR=1` | `no_progressbar=true` | Never prints a progressbar to stderr. |
| `--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. |
2 changes: 1 addition & 1 deletion docs/integrations/pre-commit.md
View file
Original file line number Diff line number Diff line change
Expand Up @@ -11,7 +11,7 @@ Add the following config to your `.pre-commit-config.yaml` file:
```yml title=.pre-commit-config.yaml
repos:
- repo: https://github.com/tconbeer/sqlfmt
rev: v0.12.0
rev: v0.13.0
hooks:
- id: sqlfmt
language_version: python
Expand Down
4 changes: 2 additions & 2 deletions docs/intro.md
View file
Original file line number Diff line number Diff line change
Expand Up @@ -21,6 +21,6 @@ sqlfmt is not a linter. It does not parse your code into an AST; it just lexes i

sqlfmt is designed to work with templated SQL files that contain jinja tags and blocks. It formats the code that users look at, and therefore doesn't need to know anything about what happens after the templates are rendered.

:::info No DDL or DML
For now, sqlfmt only works on `select` statements (which is all you need if you use sqlfmt with a dbt project). In the future, it will be extended to DDL/DML commands, as well. See [this tracking issue](https://github.com/tconbeer/sqlfmt/issues/262) for more information.
:::info Limited DDL and DML
For now, sqlfmt only works on `select`, `delete`, `grant`, `revoke`, and `create function` statements (which is all you need if you use sqlfmt with a dbt project). It is being extended to additional DDL and DML. See [this tracking issue](https://github.com/tconbeer/sqlfmt/issues/262) for more information.
:::

0 comments on commit d0adf11

Please sign in to comment.