View on GitHub

cat-file-watcher

cat-file-watcher

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

File Change Monitoring Tool - Detects file changes and executes commands

Japanese English Ask DeepWiki

Note: This document is mostly AI-generated. It was produced by submitting issues to an agent. Some parts (Concept, Usage Scenarios, Test) are manually written.

| Item | Link | |——|——–| | 📊 Development Status | generated-docs/development-status |

Overview

This is a file monitoring tool that watches for changes in file timestamps and executes commands when files are updated.

Features

Installation

  1. Clone this repository: 
    git clone https://github.com/cat2151/cat-file-watcher.git
cd cat-file-watcher
  2. Install dependencies: 
    pip install -r requirements.txt

Quick Start

Get started right away with minimal configuration! It works with just a single-line TOML file:

  1. Create a configuration file (config.toml): 
    files = [{path = "test.txt", command = "echo File changed!"}]
  2. Create the file to be monitored: 
    touch test.txt
  3. Start the file watcher: 
    python -m src --config-filename config.toml

That’s all! It will monitor test.txt and execute the command when changes occur!

Try editing the file:

echo "Test" >> test.txt

“File changed!” will be displayed in the console.

Note: The single-line format above is a valid TOML syntax using inline array notation. A more readable multi-line format is also available (see the Configuration section for details).

Usage

Run the file watcher by specifying the configuration file:

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

Arguments:

Configuration

Create a TOML configuration file to define the files to watch and the commands to execute:

# Default monitoring interval
# Time format: "1s" (1 second), "2m" (2 minutes), "3h" (3 hours), "0.5s" (0.5 seconds)
default_interval = "1s"

# Interval to check for changes in the configuration file itself
config_check_interval = "1s"

# File path for command execution logs (optional)
log_file = "command_execution.log"

# File path for error logs (optional)
# error_log_file = "error.log"

# File path for command execution suppression logs (optional)
# suppression_log_file = "suppression.log"

# Time period definitions (optional)
[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" }

Configuration Format

The configuration file must contain a [files] section where each entry maps a file name to a command:

Global Settings

Auto Update Settings

The [auto_update] section (optional) allows you to configure automatic update checks for the git repository. If configured, a background thread will periodically check for updates in the remote repository:

If the [auto_update] table itself is not present in the configuration file, the background thread for auto-updates will not be started. Also, if the current branch does not have a remote tracking branch (@{u}) configured, it will be considered “no updates,” and git pull will not be executed.

[auto_update]
enabled = true   # Set to false (default) for dry-run (notification only)
interval = "1h"  # Update check interval (default: 1 hour)

Time Period Configuration

The [time_periods] section (optional) allows you to define time periods:

Example:

[time_periods]
business_hours = { start = "09:00", end = "17:00" }  # Normal business hours
night_shift = { start = "23:00", end = "01:00" }     # Time period spanning across days

Configuration Examples

Refer to examples/config.example.toml for complete examples of various use cases.

# Set default monitoring interval to 1 second
default_interval = "1s"

# Set configuration file change check interval to 1 second
config_check_interval = "1s"

# Log file for command execution details (optional)
log_file = "command_execution.log"

# Error log file (optional)
# error_log_file = "error.log"

# Command execution suppression log file (optional)
# suppression_log_file = "suppression.log"

# Time period definitions
[time_periods]
business_hours = { start = "09:00", end = "17:00" }
after_hours = { start = "18:00", end = "08:00" }  # Spans across days

[files]
# Uses default interval (checks every 1 second)
"document.txt" = { command = "cp document.txt document.txt.bak" }

# Specifies custom interval (checks every 0.5 seconds)
"app.log" = { command = "notify-send 'Log Updated' 'New entries in app.log'", interval = "0.5s" }

# Specifies custom interval (checks every 5 seconds)
"config.ini" = { command = "systemctl reload myapp", interval = "5s" }

# Monitors only during business hours
"report.txt" = { command = "python generate_report.py", time_period = "business_hours" }

# Monitors only during after-hours (e.g., for batch processing)
"batch.csv" = { command = "./process_batch.sh", time_period = "after_hours" }

# Enables logging for important files (records timestamp, file path, and configuration content)
"important.txt" = { command = "backup.sh", enable_log = true }

How It Works

  1. The tool reads the TOML configuration file.
  2. It monitors the modification timestamps of all specified files.
  3. When a file’s timestamp changes, the associated command is executed.
  4. The configuration file itself is also monitored and automatically reloaded if it changes.
  5. This process continuously repeats until stopped with Ctrl+C.

Command Execution Mechanism

Important: Commands are executed sequentially.

For commands that require long execution times, you need to implement background execution within the command or launch it as a separate process.

Non-blocking Execution Methods:

Command Execution Output

The standard output and standard error output of executed commands are displayed in the console in real-time:

Foreground executed commands have a 30-second timeout. If this is exceeded, a timeout error will occur. For commands that require longer execution, please use background execution (using &). Commands executed in the background are not subject to the timeout limit because subprocess.run() completes immediately.

Concept

Prioritizes simple and maintainable TOML descriptions.

Usage Scenarios

For easy file update monitoring and simple operation, use cat-file-watcher.

When you want to quickly enable/disable monitoring for scattered files, use cat-file-watcher.

When you want to leverage its unique features, use cat-file-watcher.

For more advanced features, use other applications.

For TypeScript app development, etc., use a standard task runner.

Development

Environment Setup

Setting up the development environment:

# Install dependencies (for runtime)
pip install -r requirements.txt

# Install development dependencies (including Ruff)
pip install -r dev-requirements.txt

Code Quality Checks

This project uses Ruff to maintain code quality.

Running Ruff

# Linter check
ruff check src/

# Fix automatically rectifiable issues
ruff check --fix src/

# Check code format
ruff format --check src/

# Apply code format
ruff format src/

Running Tests

# Run all tests
pytest

# Run tests with verbose output
pytest -v

License

MIT License - Refer to the LICENSE file for details.

The English README.md is automatically generated by GitHub Actions using Gemini’s translation based on README.ja.md.

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