Choose a scan mode¶
TestSeal accepts exactly one source mode. The default reads working-tree
changes. --base, --staged, and --diff are mutually exclusive.
| Mode | Command | Best use |
|---|---|---|
| Working tree | testseal scan |
Local edits before staging |
| Staged index | testseal scan --staged |
pre-commit and manual staged checks |
| Git revisions | testseal scan --base BASE --head HEAD |
Pull requests and branch review |
| Unified diff | testseal scan --diff PATH |
External systems and archived patches |
Working-tree mode¶
The scan compares tracked files with HEAD and treats non-ignored untracked
files as additions. Git ignore rules are respected. Use this mode while editing
because it does not require staging.
You can compare the working tree to a different head revision:
--head cannot be combined with --staged or --diff.
Staged mode¶
The scan compares the Git index with HEAD. Unstaged changes are not included.
This makes the result match the content that the next commit would contain.
The bundled pre-commit hook uses staged mode and sets pass_filenames: false so
TestSeal can inspect the complete staged diff once.
Revision mode¶
TestSeal resolves the merge base between --base and --head, then compares
that merge base with the head revision. If --head is omitted, it defaults to
HEAD.
Revision mode is preferred in CI because TestSeal can hydrate both complete file versions. Ensure the checkout contains both revisions. A shallow checkout often lacks the base commit.
GitHub pull requests¶
The GitHub Action derives exact base and head SHAs from pull_request and
merge_group event payloads when the inputs are omitted. A full checkout is
still required:
Unified-diff mode¶
Read a UTF-8 patch from a file:
Read from standard input:
This mode validates unified hunk counts and rejects truncated input. It cannot recover syntax outside included hunks, so semantic rules can be more conservative and parse warnings can occur. Prefer Git-backed modes when the repository is available.
Path selection¶
Positional paths narrow the selected Git changes:
Use -- before paths that could be read as options:
After Git path selection, TestSeal applies include, exclude, and
test_patterns. A file omitted by configuration cannot be restored by a CLI
path argument.
include and exclude apply before Git blobs or worktree files are decoded, so
excluded generated files and virtual environments cannot fail source analysis.
Choosing for automation¶
| Environment | Recommended mode |
|---|---|
| Developer command | Working tree |
| pre-commit | Staged |
| Pull request CI | Revision |
| Merge queue | Revision |
| Patch intake service | Unified diff |
| Scheduled branch audit | Revision |