Add --exit-non-zero-on-format to formatter exit codes section#22761
Merged
MichaReiser merged 3 commits intoastral-sh:mainfrom Jan 21, 2026
Merged
Add --exit-non-zero-on-format to formatter exit codes section#22761MichaReiser merged 3 commits intoastral-sh:mainfrom
--exit-non-zero-on-format to formatter exit codes section#22761MichaReiser merged 3 commits intoastral-sh:mainfrom
Conversation
MichaReiser
reviewed
Jan 20, 2026
docs/formatter.md
Outdated
| - `2` if Ruff terminates abnormally due to invalid configuration, invalid CLI options, or an | ||
| internal error. | ||
|
|
||
| `ruff format` supports the `--exit-non-zero-on-format` command-line flag that alters its exit code behavior: |
Member
There was a problem hiding this comment.
I have a slight preference to extend the list above over adding this section. It does make it clearer which exit code it changes.
`0` if Ruff terminates successfully, and no files would be formatted if `--check` and `--exit-non-zero-on-format` were not specified.
- `1` if Ruff terminates successfully, and one or more files would be formatted if `--check` or `--exit-non-zero-on-format` were specified.
It also seems that the if --check was not specified for 1, might be incorrect, or do I misunderstand the flags @ntBre ?
Contributor
There was a problem hiding this comment.
I'm not sure I understand the question entirely, but I did some manual testing, and it seems like the flags work together as I would expect:
# no flags, reformatted, exits 0
❯ echo 'def foo(x,y,z): return x+y+z' > try.py && ruff format; echo $?
1 file reformatted
0
# --check, would reformat, exits 1
❯ echo 'def foo(x,y,z): return x+y+z' > try.py && ruff format --check; echo $?
Would reformat: try.py
1 file would be reformatted
1
# --exit-non-zero-on-format, reformatted, exits 1
❯ echo 'def foo(x,y,z): return x+y+z' > try.py && ruff format --exit-non-zero-on-format; echo $?
1 file reformatted
1
# --check AND --exit-non-zero-on-format, would reformat, still exits 1
❯ echo 'def foo(x,y,z): return x+y+z' > try.py && ruff format --check --exit-non-zero-on-format; echo $?
Would reformat: try.py
1 file would be reformatted
1I think --exit-non-zero-on-format might fit nicely in the first list:
ruff formatexits with the following status codes:
0if Ruff terminates successfully, regardless of whether any files were formatted.2if Ruff terminates abnormally due to invalid configuration, invalid CLI options, or an
internal error.
as:
1if Ruff terminates successfully, one or more files were formatted, and--exit-non-zero-on-formatwas specified
--exit-non-zero-on-format to formatter exit codes section
This file contains hidden or bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
Sign up for free
to join this conversation on GitHub.
Already have an account?
Sign in to comment
4 participants
Add this suggestion to a batch that can be applied as a single commit.This suggestion is invalid because no changes were made to the code.Suggestions cannot be applied while the pull request is closed.Suggestions cannot be applied while viewing a subset of changes.Only one suggestion per line can be applied in a batch.Add this suggestion to a batch that can be applied as a single commit.Applying suggestions on deleted lines is not supported.You must change the existing code in this line in order to create a valid suggestion.Outdated suggestions cannot be applied.This suggestion has been applied or marked resolved.Suggestions cannot be applied from pending reviews.Suggestions cannot be applied on multi-line comments.Suggestions cannot be applied while the pull request is queued to merge.Suggestion cannot be applied right now. Please check back later.
Summary
The formatter's exit codes documentation at https://docs.astral.sh/ruff/formatter/#exit-codes doesn't mention the
--exit-non-zero-on-formatflag, even though it exists (it was added in #16009) and appears in ruff format --help, and the linter flag --exit-non-zero-on-fix is properly documented in the https://docs.astral.sh/ruff/linter/#exit-codes (which was used as a reference to add the proper section in the formatter, trying to keep the consistency)