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

*This document is largely AI-generated. It was produced by submitting issues to an agent. Some parts (Concept, Usage Scenarios, Test) were written manually.

| 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

Quickstart

Get started now with minimal configuration! It works with just one line in a 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 it! It will monitor changes to test.txt and execute a command if changes are detected!

Try editing the file:

echo "Test" >> test.txt

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

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

Usage

Run the file watcher by specifying a configuration file:

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

Arguments:

Configuration

Create a TOML configuration file to define the files to monitor 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"

# Configuration file change check interval
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 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

Time Period Settings

You can define time periods in the [time_periods] section (optional):

Example:

[time_periods]
business_hours = { start = "09:00", end = "17:00" }  # Normal hours
night_shift = { start = "23:00", end = "01:00" }     # Spans across midnight

Configuration Example

For a complete example of various use cases, please refer to examples/config.example.toml.

# 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 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 midnight

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

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

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

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

# Monitor only outside business hours (e.g., for batch processing)
"batch.csv" = { command = "./process_batch.sh", time_period = "after_hours" }

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

How It Works

  1. The tool loads 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 by Ctrl+C.

Command Execution Processing Method

Important: Commands are executed sequentially.

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

Methods for Non-Blocking Execution:

Command Execution Output

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

Foreground commands have a timeout of 30 seconds, after which a timeout error will occur. For commands that require longer execution, please use background execution (using &). Commands executed in the background will not be subject to timeout limitations as subprocess.run() will complete immediately.

Concept

Prioritize simple and maintainable TOML descriptions.

Usage Scenarios

Use cat-file-watcher if you want to easily monitor file updates and operate it with minimal effort.

Use cat-file-watcher if you want to quickly enable/disable monitoring for scattered files.

Use cat-file-watcher if you want to leverage its unique features.

For more advanced functionalities, consider other applications.

For TypeScript application development and similar tasks, a standard task runner is typically used.

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 Check

This project uses Ruff to maintain code quality.

Running Ruff

# Run linter checks
ruff check src/

# Fix auto-fixable issues
ruff check --fix src/

# Check code formatting
ruff format --check src/

# Apply code formatting
ruff format src/

Running Tests

# Run all tests
pytest

# Run tests with detailed output
pytest -v

License

MIT License - See 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. 🐱