Repomix ウォッチモード完全指南 — ファイル変更を検知して自動再パックする仕組みと使い方-编程实验室

Repomix ウォッチモード完全指南 — ファイル変更を検知して自動再パックする仕組みと使い方

【免费下载链接】repomix📦 Repomix is a powerful tool that packs your entire repository into a single, AI-friendly file. Perfect for when you need to feed your codebase to Large Language Models (LLMs) or other AI tools like Claude, ChatGPT, DeepSeek, Perplexity, Gemini, Gemma, Llama, Grok, and more.项目地址: https://gitcode.com/GitHub_Trending/rep/repomix

Repomix のウォッチモード（--watch）は、コードベースを常時監視し、ファイルが変更されるたびに出力ファイルを自動的に再生成する機能です。作業しながら AI アシスタントに渡すスナップショットを常に最新に保ちたい場合に最適で、本記事を読み終えると、-wフラグの基本操作、300ms デバウンスや無視ルールの内部動作、併用できないオプションの一覧とその理由まで、ソースコード準拠の正確な知識を身につけられます。

ウォッチモードとは

Repomix は通常、コマンドを実行した時点のコードベースを一度だけパックして出力ファイルを生成します。ウォッチモードを有効にすると、Repomix はパック完了後もプロセスを常駐させ、監視対象ディレクトリ内でファイルの新規作成・変更・削除を検知するたびに自動で再パックを行います。

これにより、開発中に何度も手動でコマンドを叩き直す必要がなくなり、継続的に更新されるスナップショットを LLM（Claude、ChatGPT、DeepSeek など）へ渡し続けるワークフローを実現できます。日本語版公式ガイド watch-mode.md では「作業中も出力ファイルを最新に保てる」点がその主な利点として説明されています。

使い方

ウォッチモードは-w（または--watch）フラグで開始します。フラグの定義は cliRun.ts のWatch Modeオプショングループにあり、-w, --watchで「ファイル変更を監視して自動再パックする」動作が有効になります。

repomix --watch

実行すると、Repomix はまず一度パックし、その後も実行を続けて変更のたびに再パックします。通常のオプションと組み合わせることもできます。

# 特定のファイルだけを監視 repomix -w --include "src/**/*.ts" # 出力ファイルと形式を指定して監視 repomix --watch -o output.md --style markdown

最初の例では--includeによりsrc/**/*.tsに一致するファイルだけがパック対象となり、監視もその対象に絞られます。2 つ目の例では-o output.mdと--style markdownにより、出力先とフォーマットを指定した上で監視を開始します（--styleにはxml、markdown、json、plainが指定可能で、デフォルトはxml。詳細は command-line-options.md 参照）。

監視を停止するにはCtrl+Cを押します。内部では SIGINT（および SIGTERM）シグナルを受けて watcher を閉じ、実行中の再ビルドを待ってからプロセスが終了します（詳細は後述の「シャットダウン処理」で解説）。

動作の仕組み

ウォッチモードの実行フローは、watchAction.ts のrunWatchAction関数に実装されています。公式ガイドが説明する主要な挙動は以下のとおりです。

初回パック: Repomix はコードベースを一度パックし、監視対象のファイル数を表示します。実際のログはWatching ${packResult.safeFilePaths.length} files for changes... (Ctrl+C to stop)の形式で、パック結果（PackResult.safeFilePaths）に含まれる安全なファイル数がそのまま監視件数として報告されます（watchAction.ts）。
変更検出: 新規・変更・削除されたファイルがいずれも再パックのトリガーになります。chokidar のchange（変更）、add（追加）、unlink（削除）の 3 イベントすべてが再ビルドのスケジュール関数scheduleRebuildに接続されています（watchAction.ts）。
デバウンス: 短時間に連続する変更（ブランチの切り替えや一括保存など）はまとめられます。最後の変更から300ms待ってから再パックするため、立て続けの編集でも再構築は 1 回にまとまります。この閾値は定数REBUILD_DEBOUNCE_MS = 300として定義されており、変更イベントが来るたびにタイマーがリセットされ、最後のイベントから 300ms 経過した時点で初めて再ビルドが実行されます（watchAction.ts）。
タイムスタンプ: 再構築のたびに Repomix はタイムスタンプ（Rebuilt at HH:MM:SS）を表示するので、出力が最後に更新された時刻が分かります。

ソースコードから見るデバウンスの実装詳細

デバウンスはscheduleRebuild内でsetTimeoutを使って実装されています。特筆すべきは再ビルド中のイベントは破棄せず、キューに積んで後で実行する設計です（isRebuilding/pendingRebuildフラグ、watchAction.ts）。

変更イベントを受けるとデバウンスタイマーを（再）設定する
300ms 経過後、isRebuildingが true（再ビルド中）ならpendingRebuild = trueを立てて一旦返す
進行中の再ビルドが完了したらpendingRebuildが立っていれば直ちに次の再ビルドをスケジュールする

これにより、再ビルドが同時に 2 つ走ることは決してなく、ビルド中に発生した変更も失われません。この挙動は watchAction.test.ts の「should not start a concurrent rebuild while one is in progress」テストで検証されています。

また、Rebuilt atのタイムスタンプはnew Date().toTimeString().split(' ')[0]で生成されます（watchAction.ts）。toLocaleTimeStringではなくtoTimeStringを使うのは、システムロケール（非 ASCII 数字や AM/PM 表記）に依存せず、全プラットフォームで安定した 24 時間表記HH:MM:SSを得るためという実装上の意図がコードコメントに明記されています。

書き込み安定性の保証（awaitWriteFinish）

デバウンスに加えて、chokidar のawaitWriteFinishオプションが{ stabilityThreshold: 100 }で設定されています（watchAction.ts）。これは「ファイルサイズが 100ms 連続で変化しなくなってから変更イベントとして発火する」という設定で、エディタが書きかけの途中ファイルをパックしてしまう事故を防ぎます（定数WRITE_STABILITY_THRESHOLD_MS = 100、watchAction.ts）。

シャットダウン処理

Ctrl+Cを押すと、SIGINT/SIGTERM ハンドラ（cleanup）が実行されます。この処理は冪等に設計されており、二度押ししても watcher は一度しか閉じられません（cleanupStartedフラグによるガード、watchAction.ts）。クリーンアップ時はデバウンスタイマーをキャンセルし、実行中の再ビルドの完了を待ってから watcher を閉じ、プロセスを終了します。二重 Ctrl+C で watcher が二重に閉じられないことは watchAction.test.ts でテストされています。

無視されるファイル

ウォッチモードは通常実行と同じ無視ルールに従います。.gitignore、.repomixignore（.ignore）、組み込みのデフォルトパターン（node_modulesや.gitなど）、および--ignoreで渡したパターンを尊重します。無視されるディレクトリは監視対象から外れるため、大規模プロジェクトでもウォッチモードは効率的に動作します。

--no-gitignore:.gitignoreルールの適用を無効化
--no-dot-ignore:.ignore/.repomixignoreルールの適用を無効化
--no-default-patterns: 組み込みのデフォルトパターン（node_modules、.git、ビルドディレクトリなど）を無効化

これらのフラグは cliRun.ts の「File Selection Options」で定義されています。

ソースコードから見る監視フィルタの実装

ウォッチモードで使われる無視判定は、watchIgnore.ts のbuildWatchIgnoreFilterが生成する述語関数として実装されています。chokidar のignoredオプションにこの関数を渡すことで、パッカーと同じ無視ルールを監視側でも完全に再現します。

実装上の重要なポイントは以下のとおりです。

chokidar v4+ ではignoredに glob が使えないため、パッカーの glob パターンはminimatchで評価されます（watchIgnore.ts）。
無視されるディレクトリ自体（node_modules、.gitなど）もマッチ対象にしており、chokidar が巨大なツリーに降下してファイルディスクリプタを枯渇させる（EMFILE エラー）のを防いでいます。foo/**パターンからfoo自体のマッチャーを生成するdirMatchersがその役割を担います（watchIgnore.ts）。
パッカーと同じ無視解決パイプライン（デフォルトパターン、カスタムパターン、.git/info/exclude、.gitignore、.ignore/.repomixignore）を、globby のisGitIgnored/isIgnoredByIgnoreFilesを再利用して再現しています（watchIgnore.ts）。
出力ファイル自身（例:repomix-output.xml）も監視対象から除外され、自分が生成した出力ファイルの変更で無限ループに陥ることがありません。この点は watchIgnore.test.ts の「ignores the output file path」テストで確認できます。

ちなみに、--watchと併用した場合でも、位置引数としてディレクトリを複数渡すことで複数ルートを同時に監視できます（複数ルートのネスト・重複に対応する判定ロジックは watchIgnore.ts に実装されています）。

オプションの互換性

ウォッチモードはローカルディレクトリでのみ動作するため、次のオプションとは併用できません（コマンドラインで指定した場合でも設定ファイルで指定した場合でも同様です）。

--remoteおよび引数として渡すリモートリポジトリ URL — ウォッチモードはローカル専用
--stdoutおよび--stdin— ストリーミングモードには更新対象となる永続的な出力ファイルがない
--split-output
--skill-generate
--copy— 変更のたびに再パックするとクリップボードを繰り返し上書きしてしまう

これらのいずれかを--watchと併用すると、Repomix は競合を説明するエラーを表示して終了します。

ソースコードから見る二重の検証レイヤー

互換性チェックは2 つのレイヤーで実行されており、これが「CLI で指定しても設定ファイルで指定しても」エラーになる理由です。

CLI フラグ検証（validateWatchOptions）: cliRun.ts で、--watchが指定されている場合に--remote、--stdout、--stdin、--copy、--split-output、--skill-generate、位置引数のリモート URL を順に検査し、RepomixErrorを投げます。この検証はログレベル変更より前に実行されるため、--quietや--stdoutでエラーメッセージが抑圧されることはありません。
マージ済み設定の再検証（runWatchAction内）:validateWatchOptionsは CLI フラグしか見ないため、設定ファイル（repomix.config.json等）経由で指定された競合オプションは検出できません。そこで watchAction.ts がbuildMergedConfigで生成したマージ済み設定（デフォルト＋ファイル＋CLI を統合）に対して、output.splitOutput、output.stdoutまたはoutput.filePath === '-'、skillGenerate、output.copyToClipboardを再検査しています。

特にoutput: "-"は--stdoutと同じ標準出力モードに解決されるため（cliRun.ts）、設定ファイルで"output": "-"と書いた場合もウォッチモードではエラーになります。この「設定ファイル経由の競合も拒否する」挙動は、watchAction.test.ts の一連のテスト（split output / stdout /output: "-"/ skill generation / copy を設定ファイルで有効化したケース）でカバーされています。

また--split-outputが競合する理由はコードコメントに明記されており、「分割出力は番号付きの複数ファイルを生成し、それを watcher が拾ってループする」ためです（watchAction.ts）。

注意点

監視対象はディレクトリ単位: 個々のファイルではなく監視対象ディレクトリ自体を chokidar に渡すことで、新規作成されたファイルも確実に検知できるようにしています（watchAction.ts）。個別ファイル監視だと新規ファイルを見逃すためです。
watcher エラーはログに記録されるだけ: EMFILE や EACCES などの致命的エラーはFile watcher error:としてログ出力されます（watchAction.ts）。ただし初回リリース時点ではエラー発生後もプロセスは生存し続ける仕様であることがコードコメントに記載されており、動作が停止していることに気づきにくい可能性がある点には留意してください。
再ビルド失敗はプロセスを止めない: 再パックが失敗しても watcher は動き続け、Watch rebuild failed:のエラーログ後に後続の変更で再び再ビルドを試みます（watchAction.ts、watchAction.test.ts）。
chokidar は遅延ロード:--watchを実際に使うときだけ chokidar が動的 import されるため、通常実行時の起動コストに影響しません（watchAction.ts）。