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 largely AI-generated. It was generated by submitting issues to an agent. Some sections (concept, usage distinction, tests) 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

Quick Start

Get started immediately with minimal setup! It works with just one line in a TOML file:

  1. Create a configuration file (config.toml): 
    files = [{path = "test.txt", command = "echo γƒ•γ‚‘γ‚€γƒ«γŒε€‰ζ›΄γ•γ‚ŒγΎγ—γŸ"}]
  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! This will monitor changes to test.txt and execute a command if it changes!

Try editing the file:

echo "γƒ†γ‚Ήγƒˆ" >> test.txt

You will see β€œγƒ•γ‚‘γ‚€γƒ«γŒε€‰ζ›΄γ•γ‚ŒγΎγ—γŸβ€ printed to the console.

Note: The single-line format above is a formal TOML notation using inline array representation. 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 files to watch and 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"

# Check interval for 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 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 requires 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 optional [time_periods] section:

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 midnight

Configuration Example

For a complete example covering various use cases, 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 (checks every 1 second)
"document.txt" = { command = "cp document.txt document.txt.bak" }

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

# Specify custom interval (checks 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, 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, it executes the associated command.
  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 Handling

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.

Methods for Non-Blocking Execution:

Command Execution Output

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

Commands executed in the foreground have a timeout set to 30 seconds, beyond which 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, as subprocess.run() completes immediately.

Concept

We prioritize simple and easily maintainable TOML descriptions.

Usage Scenarios

If you want to easily monitor file changes and operate with minimal effort, use cat-file-watcher.

If you want to quickly toggle file change monitoring on/off for scattered files, use cat-file-watcher.

If you want to utilize the various unique features it offers, use cat-file-watcher.

If you need more advanced features, consider other applications.

For TypeScript application development and similar tasks, use a standard task runner.

Development

Environment Setup

To set up the development environment:

# Install dependencies (for runtime environment)
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 fixable 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 - 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. 🐱