コンテンツにスキップ

設定項目

pyproject.tomlで設定する。 このページは設定項目のリファレンスで、最小例 → プリセット設定 → 言語カテゴリによる有効化の限定 → 設定項目一覧 → グローバル設定 → ツール別除外・自動オプション・並列実行などの補助機能、の順に並ぶ。 導入手順ははじめにを参照。

例

[tool.pyfltr]
preset = "latest"
pylint-args = ["--jobs=4"]
extend-exclude = ["foo", "bar.py"]

プリセット設定

プリセットは各時点での推奨ツール構成をバージョン付きで示すスナップショット。 Python / JavaScript / TypeScript / Rust / .NET / ドキュメント系の推奨ツールを横断的に収録する。 "latest"または日付指定（"20260926" / "20260726" / "20260413" / "20260411" / "20260330"）を指定する。

[tool.pyfltr]
preset = "latest"

preset = "latest"はpyfltrの更新に伴って対象ツールの追加や既定値の変更が予告なく入ることがある。 破壊的変更を避ける場合は日付指定プリセットで固定すると、指定した日時点の構成をそのまま維持できる。

プリセットでtrueになっているツールも、次節の言語カテゴリキーがtrueの言語分だけが実際に実行される。 preset = "latest" + {language} = trueだけで、その言語の推奨ツール一式が有効化される運用を意図している。

preset "20260926"

latestが参照するプリセット。 "20260726"へpinact = trueを加えた構成。

preset "20260726"

"20260413"からpre-commit = trueをprek = trueへ差し替えた構成。

preset "20260413"

以下を設定する。

Python核（python = trueで通過）

  • ruff-format = true
  • ruff-check = true
  • mypy = true
  • pylint = true
  • pyright = true
  • pytest = true
  • uv-sort = true

JavaScript / TypeScript（javascript = trueで通過）

  • eslint = true
  • biome = true
  • oxlint = true
  • prettier = true
  • tsc = true
  • vitest = true

Rust（rust = trueで通過）

  • cargo-fmt = true
  • cargo-clippy = true
  • cargo-check = true
  • cargo-test = true
  • cargo-deny = true

.NET（dotnet = trueで通過）

  • dotnet-format = true
  • dotnet-build = true
  • dotnet-test = true

ドキュメント系と統合系（言語カテゴリに属さず、言語カテゴリキーの影響を受けない）

  • textlint = true
  • markdownlint = true
  • actionlint = true
  • typos = true
  • pre-commit = true

preset "20260411"

"20260413"からpre-commit = trueを除いた構成。 pre-commit = trueを含むプリセットは"20260413"のみ。

preset "20260330"

"20260411"からactionlint = true / typos = true / uv-sort = trueを除いた構成。

言語カテゴリによる有効化の限定

各言語カテゴリに属するツールの既定値は無効（opt-in）。 プロジェクトで利用する言語カテゴリキーをtrueにすると、プリセットで推奨されたその言語のツールが有効化される。 カテゴリキーをfalse（既定）にすると、プリセットでtrueになっていてもfalseに上書きされる。

preset = "latest" + {language} = trueの組み合わせだけで、その言語の推奨ツール一式が有効化される。

個別のツール単位では{command} = trueでの有効化・{command} = falseでの無効化も可能で、 適用優先度はpreset < 言語カテゴリによる限定 < 個別設定。

[tool.pyfltr]
preset = "latest"
python = true

各言語カテゴリキーと対象ツールは次の通り。

  • python: ruff-format・ruff-check・mypy・pylint・pyright・ty・arid・pytest・uv-sort
  • javascript: eslint・biome・oxlint・prettier・tsc・vitest（TypeScriptも同一カテゴリ）
  • rust: cargo-fmt・cargo-clippy・cargo-check・cargo-test・cargo-deny
  • dotnet: dotnet-format・dotnet-build・dotnet-test

カテゴリ同士は独立して作用する。 たとえばpython = trueを指定してもJavaScript系やRust系のツールは有効化されない。 Python系ツール一式は本体依存に同梱されているため、uvx pyfltr単発で利用できる。 JavaScript系・Rust系・.NET系は各言語のツールチェイン（Node.js・cargo・dotnet CLI）が前提となる。

対応するPython系ツールはruff-format / ruff-check / mypy / pylint / pyright / ty / arid / pytest / uv-sortの9種。 このうちtyのみpreset非収録のため、必要に応じて個別にty = trueを指定する（個別設定が最優先）。

[tool.pyfltr]
preset = "latest"
python = true
ty = true        # preset 非収録のため個別指定で追加

設定項目一覧

設定項目と既定値はpyfltr config listで確認できる。 未指定時はpyproject.tomlに明示された値のみを挿入順で表示する。 全キー一覧（既定値のままのキーを含む）を確認するときは--allを付ける。

pyfltr config list --all

--all指定時はDEFAULT_CONFIGを起点にpyproject.toml値をマージし、キー昇順で出力する。 出力形式ごとに既定値か明示値かを区別する。

  • text: 既定値の行末に(default)を付加する（明示値には何も付かない）
  • json: {"values": {key: {"value": ..., "default": bool}, ...}}の二段構造で返す
  • jsonl: 各行にdefault: boolフィールドを追加する

{command}系の項目およびツール固有の項目（prettier-check-argsなど）の詳細はツール別設定ページを参照。

  • preset : プリセット設定（前述）
  • python : Python系ツールの有効化（前述）
  • javascript : JavaScript / TypeScript系ツールの有効化（前述）
  • rust : Rust系ツールの有効化（前述）
  • dotnet : .NET系ツールの有効化（前述）
  • {command} : 各コマンドの有効/無効
  • {command}-path : 実行するコマンド
  • {command}-args : 追加のコマンドライン引数（lint/fix両モードで常に付与）
  • {command}-lint-args : 非fixモードで付与する引数（既定はtextlintのみ["--format", "compact"]）
  • {command}-fast : fastサブコマンドに含めるか否か（後述）
  • pytest-fast-targets : fast実行時だけpytestの対象を置き換えるglob（既定: 空。後述）
  • pytest-always-targets : すべての実行でpytestの対象へ加えるglob（既定: 空。後述）
  • {command}-fix-args : fix段で{command}-argsの後に追加する引数 （既定値はtextlint / markdownlint / ruff-check / eslint / biomeのみ定義）
  • {command}-targets : 対象ファイルパターンの完全上書き
  • {command}-extend-targets : 対象ファイルパターンへの追加
  • {command}-exclude : ツール別の追加除外パターン（後述）
  • {command}-pass-filenames : ファイル引数をコマンドに渡すか否か（既定: true）
  • {command}-runner : ツール起動方式。 カテゴリ委譲値（"python-runner" / "js-runner" / "bin-runner"）または直接指定値（9種）の対称12値を許容する。 既定値はツールごとに異なる（ツール別設定を参照）
  • python-runner : {command}-runner = "python-runner"の解決先（"uv" / "uvx" / "direct"、既定: "uv"）
  • js-runner : {command}-runner = "js-runner"の解決先（"pnpx" / "pnpm" / "npm" / "npx" / "yarn" / "direct"、既定: "pnpx"）
  • bin-runner : {command}-runner = "bin-runner"の解決先（"mise" / "direct"、既定: "mise"）
  • {command}-version : bin-runner対応ツールのバージョン指定（既定: "latest"）
  • pylint-pydantic : pylint実行時に--load-plugins=pylint_pydanticを自動追加するか（既定: true、後述）
  • mypy-unused-awaitable : mypy実行時に--enable-error-code=unused-awaitableを自動追加するか（既定: true、後述）
  • lychee-max-concurrency : lychee実行時の同時接続数（既定: 4。0以下でlychee既定値へ委ねる、後述）
  • jobs : linters/testersの最大並列数（既定: 8。CLIの-jオプションでも指定可能）。モノレポ検出時は同一ツールのサブプロジェクト実行を同時に開始する件数の算出にも使われる
  • command-timeout : コマンド単体のタイムアウト秒数のグローバル既定値（既定: 600秒。0で無効化）
  • {command}-timeout : per-toolのタイムアウト秒数。未指定時はcommand-timeoutのグローバル値にフォールバックする。 正の秒数を指定すると指定したコマンドのみその値で上書きし、0を指定すると同じコマンドのtimeoutのみ無効化する。 内部的には負値を「未指定」のsentinelとして扱うため、誤って負値を設定した場合もグローバル値へフォールバックする
  • retry-on-oom : LinuxのOOM killer起因でツールが強制終了された場合に自動リトライするか（既定: true。後述）
  • retry-max-attempts : OOM検知時の最大リトライ回数（既定: 1。0でリトライ無効。後述）
  • exclude : 除外するファイル名/ディレクトリ名パターン（既定値あり。ロックファイル・minify済みファイル・source mapも含む）
  • extend-exclude : 追加で除外するファイル名/ディレクトリ名パターン（既定は空）
  • respect-gitignore : .gitignoreに記載されたファイルを除外するか否か（既定: true）。 gitのルートおよびネストした.gitignore、グローバルgitignore、.git/info/excludeを全て考慮する。gitコマンドが必要
  • pre-commit-auto-skip : .pre-commit-config.yamlからpyfltr関連hookを自動検出してSKIP環境変数に追加するか（既定: true）
  • pre-commit-skip : SKIP環境変数に渡すhook IDの手動指定リスト（pre-commit-auto-skipと併用可能、既定: 空）
  • prek-auto-skip : .pre-commit-config.yamlからpyfltr関連hookを自動検出してprekへ渡すSKIP環境変数に追加するか（既定: true）
  • prek-skip : prekへ渡すSKIP環境変数のhook ID手動指定リスト（prek-auto-skipと併用可能、既定: 空）
  • archive : 実行アーカイブの有効/無効（既定: true。--no-archiveで実行単位に無効化）
  • archive-max-runs : 保存する最大世代数（既定: 100。0以下で世代軸の自動削除を無効化）
  • archive-max-size-mb : アーカイブ全体の合計サイズ上限（既定: 1024 MB。0以下でサイズ軸の自動削除を無効化）
  • archive-max-age-days : 保存期間の上限（日数。既定: 30。0以下で期間軸の自動削除を無効化）
  • cache : ファイルhashキャッシュの有効/無効（既定: true。--no-cacheで実行単位に無効化）
  • cache-max-age-hours : キャッシュエントリの保存期間（時間。既定: 12。0以下で期間軸の自動削除を無効化）
  • replace-history-max-entries : replaceサブコマンドの履歴の最大世代数（既定: 100。0以下で世代軸の自動削除を無効化）
  • replace-history-max-size-bytes : replace履歴全体の合計サイズ上限（バイト単位。 既定: 200 * 1024 * 1024（約200 MiB）。0以下でサイズ軸の自動削除を無効化）
  • replace-history-max-age-days : replace履歴の保存期間の上限（日数。既定: 30。0以下で期間軸の自動削除を無効化）
  • jsonl-diagnostic-limit : 1ツールあたりのdiagnostic出力件数上限（既定: 0 = 無制限）
  • jsonl-message-max-lines : tool.messageの行数上限（既定: 30）
  • jsonl-message-max-chars : tool.messageの文字数上限（既定: 2000）
  • textlint-protected-identifiers : textlint fixで破損させてはならない識別子のリスト。 既定値は[".NET", "Node.js", "Vue.js", "Next.js", "Nuxt.js"]。 詳細はツール別設定を参照
  • subproject-exclude : モノレポ検出時に走査・サブプロジェクト集合から除外するディレクトリ名の追加リスト。 既定値は空。.venv・node_modules・target・build・dist・.gitは常に除外する
  • subproject-use-gitignore : モノレポ検出で.gitignoreを尊重するか否か（既定: true）。 .gitignoreの対象と判定された候補は検出集合から除外する
  • subproject-uv-workspace : [tool.uv.workspace] membersを読み取ってサブプロジェクトに含めるか否か（既定: true）
  • {command}-subproject-aware : 指定したツールをサブプロジェクト単位で分割実行するか否か（per-tool）。 既定値はビルトイン定義に従う。 mypy・pylint・pytest・textlint等はtrue、typos・shellcheck・shfmt・pre-commit・prek等はfalse

prettier-check-args / prettier-write-args / shfmt-check-args / shfmt-write-argsなどの 2段階実行向け引数はツール別設定ページで詳しく扱う。

OOM自動リトライ

LinuxのOOM killerによってツールプロセスが強制終了された場合、pyfltrは自動的にリトライする。

retry-on-oomをtrue（既定）にすると、ツールのリターンコードが-9または137のときをOOM起因とみなして リトライを試みる。タイムアウト超過によるSIGKILLはOOM起因とはみなさず、リトライの対象外とする。

retry-max-attemptsはOOM検知時の最大リトライ回数を指定する。既定値は1（最大1回リトライ）。 0を指定するとリトライを無効化する（retry-on-oom: falseと同じ効果）。

JSONL出力（--output-format=jsonl）ではcommandレコードのretry_countフィールドにリトライ回数が記録される。 retry_countが0のときはフィールド自体が省略される。

Windows環境ではOOM killerが存在せずreturncodeが-9または137にならないため、本機能のリトライは実行されない。

グローバル設定

プロジェクトをまたいで共通にしたい設定（archiveの保持期間やキャッシュ保存期間など）は、 ユーザーレベルのグローバル設定ファイルに書くことでマシン単位で集約できる。

グローバル設定ファイルのパス

OS別のパスは次の通り（platformdirs.user_config_dir("pyfltr")が解決する場所）。

  • Linux: ~/.config/pyfltr/config.toml
  • macOS: ~/Library/Application Support/pyfltr/config.toml
  • Windows: %LOCALAPPDATA%\pyfltr\config.toml

環境変数PYFLTR_GLOBAL_CONFIGを設定するとそのパスを優先する （テスト容易性の確保やユーザーによる強制上書きを目的とした差し替え用。PYFLTR_CACHE_DIRと命名対称）。

書式

pyproject.tomlと同じ形式で、[tool.pyfltr]セクション配下にキーを列挙する。

[tool.pyfltr]
archive-max-age-days = 30
archive-max-size-mb = 2048
cache-max-age-hours = 24

全項目をグローバル設定ファイルに書くことができる。 ただし、archive系とcache系の計6キーのみ特殊仕様で、グローバル設定が優先される。

  • archive系（4キー）: archive / archive-max-runs / archive-max-size-mb / archive-max-age-days
  • cache系（2キー）: cache / cache-max-age-hours

これらをproject側のpyproject.tomlに書いた場合は警告が出る。 それ以外のキーはproject側が優先されるため、グローバル設定は未設定時のフォールバックとして機能する。

設定の適用順

  1. 既定値を生成する
  2. グローバル設定とproject設定（pyproject.toml）を読み込み、1つの入力にマージする
  3. archive/cache系はマージ時にグローバル側を優先する（project側に同じキーがあっても上書きされる）
  4. それ以外のキーは後勝ち（project側が優先）
  5. マージ結果にプリセット（preset）を反映する
  6. 言語カテゴリによる限定（python / javascript / rust / dotnet）を適用する

適用優先度はpreset < 言語カテゴリによる限定 < 個別設定。 pyproject.tomlが存在しないディレクトリでもグローバル設定は反映される。

設定操作

pyfltr configサブコマンドを使うと、project側のpyproject.tomlとglobal側のconfig.tomlの 両方をCLIから直接操作できる。 --globalの有無で対象ファイルを切り替える。 詳細はCLIコマンドを参照。

不正な設定値の取り扱い

設定ファイル（pyproject.tomlおよびグローバル設定）で未知のキー・型不一致・許容外の値・削除済みコマンド向けのキーを 検出した場合、該当キーを無視して既定値で処理を続行する。検出内容は警告として記録する。

本挙動は複数バージョンのpyfltrが同じ設定ファイルを参照する状況で、 新しいバージョンが追加したキーを旧バージョンが読み込んだ際の停止を回避するために採用する。 コマンドラインからの設定上書き（--config=key=value等）は対象外で、従来通りエラーで停止する。

対象ファイルパターンのカスタマイズ

各コマンドが処理する対象ファイルパターンを変更できる。

{command}-targetsでパターンを完全に上書きする。

[tool.pyfltr]
# shfmtの対象を *.bash のみに変更（既定の *.sh は対象外になる）
shfmt-targets = ["*.bash"]

{command}-extend-targetsで既存パターンに追加する。

[tool.pyfltr]
# shfmtの対象に *.sh.tmpl と dot_bashrc を追加（既定の *.sh も維持）
shfmt-extend-targets = ["*.sh.tmpl", "dot_bashrc"]
shellcheck-extend-targets = ["*.sh.tmpl", "dot_bashrc"]

両方を指定した場合、targetsで上書きした後にextend-targetsで追加する。

引数の追加

各コマンドの引数を変更したい場合、{command}-argsで既定値を完全に上書きするか、 {command}-extend-argsで既定値を保ったまま末尾へ引数を追加する。

[tool.pyfltr]
# 既定値を完全に上書きする（pyfltr既定の必須引数も含めて全て指定する必要がある）
lychee-args = ["--format", "json", "--no-progress", "--exclude=github\\.com/owner/repo/actions"]

# 既定値を保ったまま末尾へ引数を追加する
lychee-extend-args = ["--exclude=github\\.com/owner/repo/actions"]

{command}-extend-argsの対象は共通引数{command}-argsのみ。 {command}-lint-args・{command}-fix-args・{command}-check-args・{command}-write-args等の モード専用引数には対応しない。モード切替時の引数は既定値を尊重する設計のため。

pass-filenames設定

{command}-pass-filenames = falseを設定すると、コマンド実行時にファイル引数を渡さない。 プロジェクト全体を一括チェックするツール（tscなど）で使用する。

ビルトインでは、プロジェクト全体を単位として動作する以下のツールがpass-filenames = falseに設定されている。

  • tsc
  • cargo-fmt / cargo-clippy / cargo-check / cargo-test / cargo-deny
  • dotnet-format / dotnet-build / dotnet-test

pre-commit・prekの呼出しとhookのファイル選定はCLIコマンドの統合説明を参照。

カスタムコマンドでも同様に設定可能。

[tool.pyfltr]
tsc = true
# tsc は既定で pass-filenames = false のため明示不要

[tool.pyfltr.custom-commands.commitlint]
type = "linter"
path = "commitlint"
args = ["--from=HEAD~1"]
pass-filenames = false

severityによる失敗の警告化

{command}-severityを"warning"に設定すると、そのツールの失敗をJSONL command.status="warning" で記録し、 パイプライン全体のexit codeに影響させない扱いに切り替えられる。 口語表現検出など「警告で十分」な用途で、エージェントを止めずに通知だけしたい場合に使う。 カスタムコマンド・ビルトイン共通で利用できる。

[tool.pyfltr]
colloquial-check = true
colloquial-check-severity = "warning"

許容値は"error"（既定）と"warning"の2値。 "warning"設定下ではcommands_summary.needs_action.warningに集計し、 summary.guidanceのfailure系文言は出力しない。

ツール起動自体に失敗するケース（resolution_failed / timeout_exceeded）はseverityの影響を受けない。 ツール起動側の異常で警告扱いに馴染まないため、failed/resolution_failedのままとなる。

hintsによるLLM向け補足

{command}-hintsに文字列配列を指定すると、JSONL command.hints に user.<n> 連番キーで埋め込む。 LLMエージェントへ修正方針や参考文献を渡したいときに使う。 配列要素は英語推奨（command.hints / summary.guidance と同じくLLM入力前提のため）。

[tool.pyfltr]
colloquial-check = true
colloquial-check-hints = [
    "Replace colloquial Japanese expressions with formal written-language equivalents.",
]

指摘1件以上のときに限り出力する（指摘0件の実行で固定的なhintを残してLLM入力のトークンを浪費しないため）。 ビルトインコマンドにも同名キーで指定可能で、利用者ごとの運用ノウハウを永続化する用途に利用できる。

~展開

対応キーは以下。 これらに~を含めると、subprocess引数組み立て直前に展開する。 利用者ホーム配下に置いた個人ツールスクリプトをそのまま参照したい場合に使う。

  • {command}-path
  • {command}-args / {command}-extend-args / {command}-lint-args / {command}-fix-args
  • {command}-check-args / {command}-write-args
  • ruff-format-check-args
[tool.pyfltr.custom-commands.my-tool]
type = "linter"
path = "uv"
args = ["run", "--script", "~/dotfiles/scripts/my_tool.py"]

展開規則は2点。 要素先頭が~または~userの場合はos.path.expanduserで展開する。 要素内最初の=直後の~/~userも同様に展開する。 そのため"--config=~/cfg.toml"形式と["--config", "~/cfg.toml"]の分割形式のどちらでも同じく展開される。

config-files / targets / {command}-extend-targets等のglobパターンには展開を適用しない （glob内チルダの意図しない展開を防ぐため）。

ツール別除外設定

{command}-excludeを設定すると、特定ツールにのみ適用する追加の除外パターンを指定できる。 全体のexclude/extend-excludeによる除外はこれとは独立して事前に適用される。

[tool.pyfltr]
# mypy だけ vendor/ と gen_*.py を除外する
mypy-exclude = ["vendor", "gen_*.py"]

パターンの書式はextend-excludeと同じflake8風のglobパターンで、ディレクトリ指定はその配下も除外される。 --no-excludeを指定した場合、全体のexclude/extend-excludeと合わせてツール別除外も無効化される。

pass-filenames = falseのツール（tsc・cargo-*・dotnet-*など）はファイル名をコマンドに渡さないため、 {command}-excludeを設定しても効果がない。

自動オプション

各ツールの望ましいオプションを自動的にコマンドラインに追加する。 {command}-argsとは独立して動作する。

設定 既定 自動追加される引数
pylint-pydantic true --load-plugins=pylint_pydantic
mypy-unused-awaitable true --enable-error-code=unused-awaitable
lychee-max-concurrency 4 --max-concurrency=4

自動引数は{command}-argsやCLI引数と重複しないよう排除される。 真偽値の設定は不要な場合にfalseを、数値の設定はツール側の既定値へ委ねる場合に0以下を指定する。

[tool.pyfltr]
pylint-pydantic = false
mypy-unused-awaitable = false
lychee-max-concurrency = 0

並列実行

linters/testersはjobsで指定した並列数で実行される（既定: 8）。

[tool.pyfltr]
jobs = 8

CLIオプション-jでも指定でき、pyproject.tomlより優先される。

実行順はfastフラグに基づいて最適化され、fast = falseのツール（mypy、pylint、pytest等）が先に開始される。

既定値をホストの論理CPU数へ合わせていないのは、各ツールが実行中に常時CPUを占有するわけではなく、 プロセスの起動やファイルの読み書きで待つ時間があるためである。

モノレポ構成では、同一ツールをサブプロジェクトごとに実行する分もjobsから並列化する。 jobsをそのツール自身のワーカー数の推定値で割った件数を同時に開始する。 推定にはpytest-args・pylint-argsなどの-n・--jobs指定と、各サブプロジェクトのpyproject.tomlの [tool.pytest.ini_options]のaddopts・[tool.pylint]のjobsを用いる。 jobs = 8のもとでpytestへ-n 4を指定している場合は2件ずつ実行され、 ツール自身のワーカー数との積がjobsを超えない。

jobsがツール自身のワーカー数の推定値以下になる場合は、サブプロジェクトを1件ずつ順に実行する。 並列化しても報告順はサブプロジェクトの相対パスの昇順で安定する。

fastエイリアス

fastサブコマンドで実行されるコマンドは、各コマンドの{command}-fast設定で制御される。

[tool.pyfltr]
# mypyをfastに追加
mypy-fast = true
# textlintをfastから除外
textlint-fast = false

カスタムコマンドもfast = trueでfastエイリアスに追加できる。

fast実行時のpytest対象

pytest-fast-targetsへglob（文字列または文字列の配列）を指定すると、fast実行時のpytestは一致するテストファイルだけを実行する。 変更ファイルに依らず毎回確かめたいテスト（リポジトリ全体の不変条件を確かめるテストなど）を、全テストを収集せずにpre-commitから実行する用途を想定する。

[tool.pyfltr]
pytest = true
pytest-fast-targets = ["*_invariant_test.py"]
  • 値が空でなければ、pytest-fast = falseでもpytestはfastエイリアスに含まれる。pytest = falseの場合は実行しない
  • fast実行はpyfltr fastと、--commandsへfastを含む実行（pyfltr run --commands=fastなど）を指す。pyfltr fast --commands=pytestも含む
  • 対象は位置引数と--changed-sinceに依らず、プロジェクト全域から選ぶ。Markdownだけを変更したコミットでも指定したテストが動く
  • globの一致はpytest-targetsと同じ規則で判定し、pytest-targetsの代わりに使う。exclude・extend-exclude・.gitignore・pytest-excludeによる除外はそのまま適用する
  • 一致するファイルが無い場合はpytestを起動せず、対象ファイル0件として扱う（全テストの収集へは戻らない）
  • pytest-argsなどの引数は通常どおり渡す。マーカー式は追加しない
  • fast以外の実行（pyfltr run・pyfltr ci、--commands=pytestなど）の対象は変わらない。値が空（既定）の場合もfastの対象と参加判定は従来どおりとなる
  • モノレポでは各サブプロジェクトの設定に従い、そのサブプロジェクトのファイルだけをそのディレクトリで実行する。起点に指定が無くても、指定を持つサブプロジェクトがあればfastでpytestを実行する

常に加えるpytest対象

pytest-always-targetsへglob（文字列または文字列の配列）を指定すると、pytestを実行するすべての実行で、一致するテストファイルを通常の対象へ加える。 変更したファイルだけを渡した実行でも、別のファイルに定義した不変条件のテスト（リポジトリ全体の状態を確かめるテストなど）を同じ実行で動かす用途を想定する。

[tool.pyfltr]
pytest = true
pytest-always-targets = ["*_invariant_test.py"]
  • 対象は「位置引数と--changed-sinceで決まる通常の対象」と「プロジェクト全域から指定globに一致したファイル」の和集合になる。同じファイルは1回だけ渡す
  • pyfltr run・run-for-agent・ci・MCPのrunとfast実行に適用する。fastではpytest-fast-targetsで置き換えた対象へ加える
  • pytest-fast-targetsは置き換え、pytest-always-targetsは追加という違いがある。fastへの参加はpytest-fastとpytest-fast-targetsが決め、pytest-always-targetsだけではpytestをfastへ加えない
  • pytest = falseの場合と、--commandsでpytestを選ばない実行では実行しない
  • exclude・extend-exclude・.gitignore・pytest-excludeによる除外と、それらを無効化する--no-exclude・--no-gitignoreはそのまま適用する
  • --only-failedでは、追加したテストも候補に含めたうえで前回失敗したファイルだけを実行する
  • モノレポでは各サブプロジェクトの設定に従い、そのサブプロジェクトのファイルだけをそのディレクトリで実行する。変更したファイルが別のサブプロジェクトにだけある場合も、指定を持つサブプロジェクトのテストを実行する

出力順序

非TUIモード（--no-ui、--ci、または非対話端末）では、既定の動作として全コマンドの完了後に 成功コマンド詳細 → 失敗コマンド詳細 → summaryの順でまとめて出力する。 pyfltr ... | tail -Nのようにパイプで末尾だけ切り出してもsummaryと失敗情報が末尾に残るため、 Claude Codeなど末尾だけを読み取るツールでも実行結果を把握できる。

従来の「各コマンドの完了時に即座に詳細ログを出力する」挙動を使いたい場合は--streamを指定する。

個別のツール設定（2段階実行、直接実行 / js-runner / bin-runnerのカテゴリ別設定、 mise-auto-trustによるmise未信頼の自動対応等）の詳細はツール別設定、 カスタムコマンドの仕様と事例はプロジェクト固有チェックの追加を参照。