View on GitHub

cat-file-watcher

cat-file-watcher

cat-file-watcher - Cat is watching your file -

ファイル変更監視ツール - ファイルの変更を検知してコマンドを実行

Japanese English

※このドキュメントは大部分がAI生成です。issueをagentに投げて生成させました。一部（コンセプト、使い分け、test）は人力で書いています

| 項目 | リンク | |——|——–| | 📊 開発状況 | generated-docs/development-status |

概要

ファイルのタイムスタンプの変更を監視し、ファイルが更新されたときにコマンドを実行するファイル監視ツールです。

特徴

インストール

  1. このリポジトリをクローン: 
    git clone https://github.com/cat2151/cat-file-watcher.git
cd cat-file-watcher
  2. 依存パッケージをインストール: 
    pip install -r requirements.txt

クイックスタート

最小限の設定で今すぐ始めましょう！たった1行のTOMLファイルで動作します:

  1. 設定ファイルを作成（config.toml）: 
    files = [{path = "test.txt", command = "echo ファイルが変更されました"}]
  2. 監視対象のファイルを作成: 
    touch test.txt
  3. ファイルウォッチャーを起動: 
    python -m src --config-filename config.toml

これだけで、test.txt の変更を監視し、変更があればコマンドを実行します！

ファイルを編集してみてください:

echo "テスト" >> test.txt

コンソールに「ファイルが変更されました」と表示されます。

ポイント: 上記の1行形式は、インライン配列表記を使ったTOMLの正式な記法です。より読みやすい複数行形式も使えます（詳細は設定セクションを参照）。

使い方

設定ファイルを指定してファイルウォッチャーを実行:

python -m src --config-filename config.toml

引数:

設定

監視するファイルと実行するコマンドを定義するTOML設定ファイルを作成します:

# デフォルトの監視間隔
# 時間フォーマット: "1s"（1秒）、"2m"（2分）、"3h"（3時間）、"0.5s"（0.5秒）
default_interval = "1s"

# 設定ファイル自体の変更チェック間隔
config_check_interval = "1s"

# コマンド実行ログのファイルパス（省略可）
log_file = "command_execution.log"

# エラーログのファイルパス（省略可）
# error_log_file = "error.log"

# コマンド実行抑制ログのファイルパス（省略可）
# suppression_log_file = "suppression.log"

# 時間帯の定義（省略可）
[time_periods]
business_hours = { start = "09:00", end = "17:00" }
night_shift = { start = "23:00", end = "01:00" }

[files]
"myfile.txt" = { command = "echo 'File changed!'" }
"script.py" = { command = "python -m pytest tests/", interval = "2s" }
"src/main.py" = { command = "make build", suppress_if_process = "vim|emacs|code" }
"batch.csv" = { command = "./process.sh", time_period = "night_shift" }
"important.txt" = { command = "backup.sh", enable_log = true }
"lib/module.c" = { command = "gcc -c module.c -o module.o", cwd = "./lib" }

設定フォーマット

設定ファイルには、各エントリがファイル名とコマンドをマッピングする [files] セクションが必要です:

グローバル設定

時間帯設定

[time_periods] セクション（省略可）で時間帯を定義できます:

例:

[time_periods]
business_hours = { start = "09:00", end = "17:00" }  # 通常の時間帯
night_shift = { start = "23:00", end = "01:00" }     # 日をまたぐ時間帯

設定例

様々なユースケースの完全な例は examples/config.example.toml を参照してください。

# デフォルトの監視間隔を1秒に設定
default_interval = "1s"

# 設定ファイル自体の変更チェック間隔を1秒に設定
config_check_interval = "1s"

# コマンド実行の詳細を記録するログファイル（省略可）
log_file = "command_execution.log"

# エラーログファイル（省略可）
# error_log_file = "error.log"

# コマンド実行抑制ログファイル（省略可）
# suppression_log_file = "suppression.log"

# 時間帯の定義
[time_periods]
business_hours = { start = "09:00", end = "17:00" }
after_hours = { start = "18:00", end = "08:00" }  # 日をまたぐ

[files]
# デフォルト間隔を使用（1秒ごとにチェック）
"document.txt" = { command = "cp document.txt document.txt.bak" }

# カスタム間隔を指定（0.5秒ごとにチェック）
"app.log" = { command = "notify-send 'Log Updated' 'New entries in app.log'", interval = "0.5s" }

# カスタム間隔を指定（5秒ごとにチェック）
"config.ini" = { command = "systemctl reload myapp", interval = "5s" }

# 営業時間のみ監視
"report.txt" = { command = "python generate_report.py", time_period = "business_hours" }

# 営業時間外のみ監視（バッチ処理など）
"batch.csv" = { command = "./process_batch.sh", time_period = "after_hours" }

# 重要なファイルのログを有効化（タイムスタンプ、ファイルパス、設定内容を記録）
"important.txt" = { command = "backup.sh", enable_log = true }

動作の仕組み

  1. ツールがTOML設定ファイルを読み込みます
  2. 指定されたすべてのファイルの更新タイムスタンプを監視します
  3. ファイルのタイムスタンプが変更されると、関連するコマンドを実行します
  4. 設定ファイル自体も監視し、変更があれば自動的に再読み込みします
  5. このプロセスはCtrl+Cで停止するまで継続的に繰り返されます

コマンド実行の処理方式

重要: コマンドは順次実行（シーケンシャル）されます。

長時間実行が必要なコマンドの場合は、コマンド内でバックグラウンド実行するか、別プロセスで起動する工夫が必要です。

ノンブロッキング実行の方法:

コマンド実行時の出力

実行されたコマンドの標準出力および標準エラー出力は、リアルタイムでコンソールに表示されます:

フォアグラウンドで実行されるコマンドのタイムアウトは30秒に設定されており、それを超えるとタイムアウトエラーが発生します。長時間実行が必要なコマンドの場合は、バックグラウンド実行（& を使用）してください。バックグラウンド実行されたコマンドは、subprocess.run()が即座に完了するため、タイムアウトの制限を受けません。

コンセプト

toml記述内容がシンプルでメンテしやすいことを優先します

使い分け

手軽にファイル更新監視したい場合、楽に運用したい場合は、cat-file-watcher

散在するファイルを手早く更新監視on/offしたい場合は、cat-file-watcher

これにしかない各種機能を利用したい場合は、cat-file-watcher

もっと高度な機能を使いたい場合は、ほかのアプリ

TypeScriptアプリ開発等には、スタンダードにタスクランナー

開発

環境構築

開発環境のセットアップ:

# 依存パッケージのインストール（実行環境用）
pip install -r requirements.txt

# 開発用依存パッケージのインストール（Ruffを含む）
pip install -r dev-requirements.txt

コード品質チェック

このプロジェクトでは、コード品質を保つためにRuffを使用しています。

Ruffの実行

# リンターチェック
ruff check src/

# 自動修正可能な問題を修正
ruff check --fix src/

# コードフォーマットのチェック
ruff format --check src/

# コードフォーマットを適用
ruff format src/

テストの実行

# 全テストの実行
pytest

# 詳細出力付きでテストを実行
pytest -v

ライセンス

MIT License - 詳細はLICENSEファイルを参照してください

※英語版README.mdは、README.ja.mdを元にGeminiの翻訳でGitHub Actionsにより自動生成しています

Big Brother watched your files. Now the cat does. 🐱