# Behavior, safety, and performance
## Inputs
profmt accepts standard input, files, and directories.
- Directory traversal selects `.proto` files.
- Standard ignore files such as `.gitignore` apply.
- Hidden paths are included unless an ignore rule excludes them.
- Symbolic links are rejected and never followed.
- Explicit files are accepted regardless of extension.
File discovery and formatting run in parallel. Results are reported in sorted
path order.
Use `--threads N` to select a fixed worker count. Directory discovery uses at
most four workers because additional walkers increase filesystem contention.
Single-threaded mode bypasses the Rayon pool.
## Modes and exit status
Without `--write` or `--check`, profmt requires one input and prints the
formatted source to standard output.
`--write` replaces changed files. `--check` changes no files and exits with
status 1 if any file would change. Add `--diff` to print unified diffs.
| 0 | Every input succeeded, and `--check` found no changes. |
| 1 | `--check` found at least one change. |
| 2 | An input, configuration, or formatter operation failed. |
## Layout
profmt prints one statement per line. By default a declaration stays on its
line however long it is: a dangling `returns`, a lone option in brackets, or
a value separated from its `option` is worse than a long line. Each of those
breaks is available as an opt-in: `rpc_signature_layout`,
`field_options_layout` and `option_value_layout`.
A text-format message literal is data rather than a declaration, so it
breaks one entry per line when it does not fit, keeping the separators the
source used.
Comments are never re-wrapped. A comment on the same line as code stays at
the end of that line; a comment on its own line stays on its own line; a
multi-line block comment is re-indented under its opening `/*`. A `//`
comment inside a statement moves to the end of the statement's line.
## Safe writes
Before profmt replaces a file, it:
1. Rejects symbolic links and non-regular files.
2. Writes a unique temporary file in the same directory.
3. Preserves the original permissions.
4. Re-reads the source and rejects concurrent changes.
5. Renames the completed temporary file over the source.
If cleanup also fails, profmt reports both the original error and the cleanup
error.
## Failures
profmt returns an error for invalid UTF-8, parse errors, and invalid
configuration. It does not replace invalid text.
An input byte-order mark is preserved.
## Performance
A release build checked 603 `.proto` files (3.1 MB) on a 14-core Apple M4 Max
with a warm filesystem cache:
| 1 | 0.20 s |
| 14 | 0.03 s |
The command was `profmt --check .`. The measurement includes ignore-aware
discovery, file reads, parsing, layout, and comparison. Parsing accounts for
most of the single-threaded time. Results vary with the corpus, hardware,
filesystem cache, and configured worker count.
tree-sitter parses each file once. profmt walks the tree once, constructing a
compact arena-backed document; unchanged source remains byte spans instead of
copied strings, and a check compares the rendering against the source without
allocating it.