trs-file-backup 2.0.1__py3-none-any.whl

trs_file_backup/__init__.py

@@ -0,0 +1 @@
+__version__ = "2.0.1"

trs_file_backup/backup.py

@@ -0,0 +1,131 @@
+"""File backup operations."""
+
+import shutil
+from datetime import datetime
+from pathlib import Path
+from typing import List, Optional
+
+from trs_file_backup.state import StateManager
+
+
+class BackupManager:
+    """Manages file backup operations."""
+
+    def __init__(
+        self,
+        source_path: Path,
+        destination_path: Path,
+        excluded_patterns: List[str],
+        state: Optional[StateManager],
+    ):
+        """Initialize backup manager.
+
+        Args:
+            source_path: Source directory path
+            destination_path: Destination directory path
+            excluded_patterns: List of exclusion patterns
+            state: StateManager instance or None
+        """
+        self.source_path = source_path
+        self.destination_path = destination_path
+        self.excluded_patterns = excluded_patterns
+        self.state = state
+
+    @staticmethod
+    def generate_backup_filename(filename: str, timestamp: datetime) -> str:
+        """Generate timestamped backup filename.
+
+        Args:
+            filename: Original filename (can include path)
+            timestamp: Timestamp for the backup
+
+        Returns:
+            Formatted filename: filename_YYYY_MM_DD__HH_MM_SS.ext
+        """
+        # Extract just the filename if path is included
+        path = Path(filename)
+        name_without_ext = path.stem
+        extension = path.suffix
+        timestamp_str = timestamp.strftime("%Y_%m_%d__%H_%M_%S")
+        return f"{name_without_ext}_{timestamp_str}{extension}"
+
+    @staticmethod
+    def matches_exclusion_pattern(filename: str, patterns: List[str]) -> bool:
+        """Check if filename matches any exclusion pattern.
+
+        Hidden files (starting with .) are always excluded.
+
+        Args:
+            filename: Filename to check
+            patterns: List of exclusion patterns (supports wildcards)
+
+        Returns:
+            True if filename should be excluded, False otherwise
+        """
+        # Always exclude hidden files
+        if filename.startswith("."):
+            return True
+
+        # Check against patterns
+        path = Path(filename)
+        for pattern in patterns:
+            if path.match(pattern):
+                return True
+
+        return False
+
+    def get_files_to_backup(self) -> List[Path]:
+        """Get list of files that need to be backed up.
+
+        Returns:
+            List of file paths that should be backed up
+        """
+        files_to_backup = []
+
+        # Iterate only top-level files (no subdirectories)
+        for item in self.source_path.iterdir():
+            # Skip directories
+            if item.is_dir():
+                continue
+
+            # Skip excluded files
+            if self.matches_exclusion_pattern(item.name, self.excluded_patterns):
+                continue
+
+            # If no state exists, backup all files
+            if self.state is None:
+                files_to_backup.append(item)
+                continue
+
+            # Check if file is modified
+            current_mtime = item.stat().st_mtime
+            if self.state.is_modified(item.name, current_mtime):
+                files_to_backup.append(item)
+
+        return files_to_backup
+
+    def backup_file(self, source_file: Path, timestamp: datetime) -> Path:
+        """Backup a single file with timestamp.
+
+        Args:
+            source_file: Path to source file
+            timestamp: Timestamp for backup filename
+
+        Returns:
+            Path to the created backup file
+
+        Raises:
+            PermissionError: If file cannot be accessed
+            OSError: If file is locked or other IO error occurs
+        """
+        # Ensure destination directory exists
+        self.destination_path.mkdir(parents=True, exist_ok=True)
+
+        # Generate backup filename
+        backup_filename = self.generate_backup_filename(source_file.name, timestamp)
+        destination_file = self.destination_path / backup_filename
+
+        # Copy file (preserves metadata)
+        shutil.copy2(source_file, destination_file)
+
+        return destination_file

trs_file_backup/logger.py

@@ -0,0 +1,163 @@
+"""Logging functionality for backup operations."""
+
+import logging
+from pathlib import Path
+from typing import List
+
+
+class BackupLogger:
+    """Handles logging of backup operations to file."""
+
+    def __init__(self, destination_path: Path):
+        """Initialize logger.
+
+        Args:
+            destination_path: Destination directory where log file will be created
+        """
+        self.destination_path = destination_path
+        self.log_file_path = destination_path / "backup.log"
+
+        # Ensure destination directory exists
+        destination_path.mkdir(parents=True, exist_ok=True)
+
+        # Configure logger
+        self.logger = logging.getLogger("trs_file_backup")
+        self.logger.setLevel(logging.INFO)
+
+        # Remove existing handlers to avoid duplicates
+        # Close handlers properly to avoid ResourceWarning
+        for handler in self.logger.handlers[:]:
+            handler.close()
+            self.logger.removeHandler(handler)
+
+        # Create file handler with UTF-8 encoding and append mode
+        handler = logging.FileHandler(
+            self.log_file_path,
+            mode="a",
+            encoding="utf-8",
+        )
+
+        # Set format
+        formatter = logging.Formatter(
+            "[%(asctime)s] [%(levelname)s] %(message)s",
+            datefmt="%Y-%m-%d %H:%M:%S",
+        )
+        handler.setFormatter(formatter)
+
+        self.logger.addHandler(handler)
+
+    def log_session_start(
+        self,
+        command: str,
+        source_path: Path,
+        destination_path: Path,
+        excluded_patterns: List[str],
+        debounce_seconds: int,
+    ) -> None:
+        """Log session start with configuration.
+
+        Args:
+            command: Command being executed (init, run, watch)
+            source_path: Source directory path
+            destination_path: Destination directory path
+            excluded_patterns: List of exclusion patterns
+            debounce_seconds: Debounce delay in seconds
+        """
+        self.logger.info("=" * 10 + " Session Started " + "=" * 10)
+        self.logger.info(f"Command: {command}")
+        self.logger.info(f"Source: {source_path}")
+        self.logger.info(f"Destination: {destination_path}")
+        self.logger.info(f"Exclusion patterns: {', '.join(excluded_patterns)}")
+        self.logger.info(f"Debounce delay: {debounce_seconds} seconds")
+
+    def log_session_end(self, files_backed_up: int = 0, files_total: int = 0) -> None:
+        """Log session end with summary.
+
+        Args:
+            files_backed_up: Number of files successfully backed up
+            files_total: Total number of files processed
+        """
+        if files_total > 0:
+            self.logger.info(f"Session summary: {files_backed_up} of {files_total} files backed up")
+        self.logger.info("=" * 10 + " Session Ended " + "=" * 10)
+        # Add three blank lines for better session separation
+        self.logger.info("")
+        self.logger.info("")
+        self.logger.info("")
+
+    def log_init_success(self) -> None:
+        """Log successful initialization."""
+        self.logger.info("Backup tracking initialized successfully")
+
+    def log_found_files(self, count: int) -> None:
+        """Log number of files found.
+
+        Args:
+            count: Number of modified files found
+        """
+        self.logger.info(f"Found {count} modified files")
+
+    def log_file_backed_up(self, source_name: str, backup_name: str) -> None:
+        """Log successful file backup.
+
+        Args:
+            source_name: Original filename
+            backup_name: Backup filename with timestamp
+        """
+        self.logger.info(f"Backed up: {source_name} → {backup_name}")
+
+    def log_file_excluded(self, filename: str, pattern: str) -> None:
+        """Log excluded file.
+
+        Args:
+            filename: Name of excluded file
+            pattern: Pattern that matched
+        """
+        self.logger.warning(f"File excluded: {filename} (matches: {pattern})")
+
+    def log_file_locked(self, filename: str) -> None:
+        """Log locked file warning.
+
+        Args:
+            filename: Name of locked file
+        """
+        self.logger.warning(f"File locked, skipping: {filename}")
+
+    def log_error(self, message: str) -> None:
+        """Log error message.
+
+        Args:
+            message: Error message
+        """
+        self.logger.error(message)
+
+    def log_file_modified(self, filename: str) -> None:
+        """Log file modification event (watch mode).
+
+        Args:
+            filename: Name of modified file
+        """
+        self.logger.info(f"File modified: {filename}")
+
+    def log_watch_started(self) -> None:
+        """Log watch mode started."""
+        self.logger.info("Watch mode started, monitoring for changes...")
+
+    def log_watch_stopped(self) -> None:
+        """Log watch mode stopped."""
+        self.logger.info("Watch mode stopped by user (Ctrl+C)")
+
+    def log_backup_completed(self, backed_up: int, total: int) -> None:
+        """Log backup operation completion.
+
+        Args:
+            backed_up: Number of files backed up successfully
+            total: Total number of files attempted
+        """
+        self.logger.info(f"Backup operation completed: {backed_up} of {total} files backed up")
+
+    def close(self) -> None:
+        """Close all handlers and clean up resources."""
+        for handler in self.logger.handlers[:]:
+            handler.close()
+            self.logger.removeHandler(handler)

trs_file_backup/main.py

@@ -0,0 +1,583 @@
+"""Main CLI application for trs-file-backup."""
+
+import time
+from datetime import datetime
+from pathlib import Path
+from typing import Any, List
+
+import typer
+from rich.console import Console
+from watchdog.events import FileSystemEventHandler
+from watchdog.observers import Observer
+
+from trs_file_backup import __version__
+from trs_file_backup.backup import BackupManager
+from trs_file_backup.logger import BackupLogger
+from trs_file_backup.state import StateManager
+
+app = typer.Typer(
+    name="trs-file-backup",
+    help="trs-file-backup - Monitor and backup modified files with timestamps",
+    add_completion=False,
+    rich_markup_mode="rich",
+    epilog="""\b
+Examples:
+  trs-file-backup run --source ./myproject --destination ./backup
+  trs-file-backup watch --source ./myproject --destination ./backup
+
+Use 'trs-file-backup COMMAND --help' for detailed information on each command.
+""",
+)
+console = Console()
+
+
+def version_callback(value: bool) -> None:
+    """Show version and exit."""
+    if value:
+        print(f"trs-file-backup version {__version__}")
+        raise typer.Exit(0)
+
+
+@app.callback(invoke_without_command=True)
+def main(
+    ctx: typer.Context,
+    version: bool = typer.Option(
+        False,
+        "--version",
+        "-v",
+        help="Show version and exit",
+        is_eager=True,
+    ),
+) -> None:
+    """
+    trs-file-backup - Monitor and backup modified files with timestamps
+
+    This tool helps you create timestamped backups of modified files from a
+    source directory to a destination directory. It supports one-time backups,
+    initialization, and continuous monitoring.
+
+    Options:
+      -v, --version    Show version and exit
+
+    \b
+    Examples:
+      trs-file-backup run --source ./myproject --destination ./backup
+      trs-file-backup watch --source ./myproject --destination ./backup
+
+    Use 'trs-file-backup COMMAND --help' for more information on a specific command.
+    """
+    if version:
+        version_callback(True)
+
+    if ctx.invoked_subcommand is None:
+        console.print(ctx.get_help())
+
+
+@app.command()
+def init(
+    source: Path = typer.Option(  # noqa: B008
+        ...,
+        "--source",
+        help="Source directory to monitor",
+        exists=True,
+        file_okay=False,
+        dir_okay=True,
+        resolve_path=True,
+    ),
+    destination: Path = typer.Option(  # noqa: B008
+        ...,
+        "--destination",
+        help="Destination backup directory",
+        file_okay=False,
+        dir_okay=True,
+        resolve_path=True,
+    ),
+    exclude: List[str] = typer.Option(  # noqa: B008
+        [],
+        "--exclude",
+        help="File/directory patterns to exclude (can be repeated)",
+    ),
+    debounce: int = typer.Option(
+        2,
+        "--debounce",
+        help="Seconds to wait before backup (default: 2)",
+        min=0,
+    ),
+) -> None:
+    """Initialize backup tracking for a directory.
+
+    This command sets up backup tracking by creating a state file in the destination
+    directory. The next 'run' or 'watch' command will back up all files (first
+    full backup). Subsequent runs will only backup modified files.
+
+    Examples:
+
+      # Basic initialization
+      trs-file-backup init --source C:\\Projects\\MyApp --destination C:\\Backup\\MyApp
+
+      # Initialize with exclusions and custom debounce
+      trs-file-backup init --source ./src --destination ./backup --exclude "*.log" --exclude "*.tmp" --debounce 5
+
+    Note:
+      Exclusion patterns and debounce setting specified here are saved and used for all future backups.
+    """
+    logger = None
+    try:
+        # Add default exclusions
+        excluded_patterns = [".backup_state.json", *exclude]
+
+        # Create logger
+        logger = BackupLogger(destination)
+
+        # Log session start
+        logger.log_session_start(
+            command="init",
+            source_path=source,
+            destination_path=destination,
+            excluded_patterns=excluded_patterns,
+            debounce_seconds=debounce,
+        )
+
+        # Create initial state
+        state = StateManager(
+            source_path=source,
+            destination_path=destination,
+            debounce_seconds=debounce,
+            excluded_patterns=excluded_patterns,
+            files={},
+        )
+
+        # Save state
+        state.save()
+
+        # Log success
+        logger.log_init_success()
+        logger.log_session_end()
+
+        # Show user message
+        console.print(f"[green]✓[/green] Initialized backup tracking for {source}")
+        console.print(f"State file saved to {state.state_file_path}")
+        console.print(f"Log file created: {destination / 'backup.log'}")
+        console.print("Next run will back up all files.")
+
+    except Exception as e:
+        console.print(f"[red]Error:[/red] {e}")
+        raise typer.Exit(code=1) from None
+    finally:
+        if logger is not None:
+            logger.close()
+
+
+@app.command()
+def run(
+    source: Path = typer.Option(  # noqa: B008
+        ...,
+        "--source",
+        help="Source directory to monitor",
+        exists=True,
+        file_okay=False,
+        dir_okay=True,
+        resolve_path=True,
+    ),
+    destination: Path = typer.Option(  # noqa: B008
+        ...,
+        "--destination",
+        help="Destination backup directory",
+        file_okay=False,
+        dir_okay=True,
+        resolve_path=True,
+    ),
+    exclude: List[str] = typer.Option(  # noqa: B008
+        [],
+        "--exclude",
+        help="File/directory patterns to exclude (can be repeated)",
+    ),
+    debounce: int = typer.Option(
+        2,
+        "--debounce",
+        help="Seconds to wait before backup (default: 2)",
+        min=0,
+    ),
+    dry_run: bool = typer.Option(
+        False,
+        "--dry-run",
+        help="Show what would be backed up without copying",
+    ),
+) -> None:
+    """Execute a one-time backup of modified files.
+
+    This command scans the source directory for files that have been modified
+    since the last backup and creates timestamped copies in the destination
+    directory. Only files changed after the last backup run are processed.
+
+    Examples:
+
+      # Basic backup
+      trs-file-backup run --source C:\\Projects\\MyApp --destination C:\\Backup\\MyApp
+
+      # Exclude log files
+      trs-file-backup run --source ./src --destination ./backup --exclude "*.log"
+
+      # Multiple exclusions with custom debounce
+      trs-file-backup run --source ./src --destination ./backup --exclude "*.log" --exclude "temp_*" --debounce 5
+
+      # Preview without copying
+      trs-file-backup run --source ./src --destination ./backup --dry-run
+    """
+    logger = None
+    try:
+        # Add default exclusions
+        excluded_patterns = [".backup_state.json", *exclude]
+
+        # Load or create state
+        state_file = destination / ".backup_state.json"
+        state = StateManager.load(state_file)
+
+        if state is None:
+            # Create new state
+            state = StateManager(
+                source_path=source,
+                destination_path=destination,
+                debounce_seconds=debounce,
+                excluded_patterns=excluded_patterns,
+                files={},
+            )
+        else:
+            # Update state with current parameters
+            state.excluded_patterns = excluded_patterns
+            state.debounce_seconds = debounce
+
+        # Create logger
+        logger = BackupLogger(destination)
+
+        # Log session start
+        logger.log_session_start(
+            command="run",
+            source_path=source,
+            destination_path=destination,
+            excluded_patterns=excluded_patterns,
+            debounce_seconds=debounce,
+        )
+
+        # Create backup manager
+        backup_manager = BackupManager(
+            source_path=source,
+            destination_path=destination,
+            excluded_patterns=excluded_patterns,
+            state=state,
+        )
+
+        # Get files to backup
+        console.print(f"Scanning source directory: {source}")
+        files_to_backup = backup_manager.get_files_to_backup()
+        logger.log_found_files(len(files_to_backup))
+
+        if len(files_to_backup) == 0:
+            console.print("[yellow]No modified files found.[/yellow]")
+            logger.log_session_end(0, 0)
+            return
+
+        console.print(f"Found {len(files_to_backup)} modified files")
+
+        if dry_run:
+            console.print("\n[yellow]Dry-run mode: No files will be copied[/yellow]\n")
+            for file in files_to_backup:
+                timestamp = datetime.now()
+                backup_name = BackupManager.generate_backup_filename(file.name, timestamp)
+                console.print(f"  Would backup: {file.name} → {backup_name}")
+            logger.log_session_end(0, len(files_to_backup))
+            return
+
+        # Backup files
+        console.print("Backing up files...")
+        backed_up_count = 0
+        failed_count = 0
+
+        for file in files_to_backup:
+            try:
+                # Wait debounce time
+                time.sleep(debounce)
+
+                # Backup file
+                timestamp = datetime.now()
+                backup_path = backup_manager.backup_file(file, timestamp)
+
+                # Update state
+                state.update_file_timestamp(file.name, file.stat().st_mtime)
+
+                # Log success
+                logger.log_file_backed_up(file.name, backup_path.name)
+                console.print(f"  [green]✓[/green] {file.name} → {backup_path.name}")
+                backed_up_count += 1
+
+            except PermissionError:
+                logger.log_error(f"Permission denied: {file.name}")
+                console.print(f"  [red]✗[/red] Permission denied: {file.name}")
+                failed_count += 1
+
+            except OSError:
+                logger.log_file_locked(file.name)
+                console.print(f"  [yellow]⚠[/yellow] File locked, skipping: {file.name}")
+                failed_count += 1
+
+        # Save updated state
+        state.save()
+
+        # Log completion
+        logger.log_backup_completed(backed_up_count, len(files_to_backup))
+        logger.log_session_end(backed_up_count, len(files_to_backup))
+
+        # Show summary
+        console.print(f"\n[green]Successfully backed up {backed_up_count} files to {destination}[/green]")
+        if failed_count > 0:
+            console.print(f"[yellow]Failed: {failed_count} files[/yellow]")
+        console.print(f"Logging to: {destination / 'backup.log'}")
+
+    except Exception as e:
+        console.print(f"[red]Error:[/red] {e}")
+        raise typer.Exit(code=1) from None
+    finally:
+        if logger is not None:
+            logger.close()
+
+
+class BackupEventHandler(FileSystemEventHandler):
+    """Handler for file system events in watch mode."""
+
+    def __init__(
+        self,
+        backup_manager: BackupManager,
+        state: StateManager,
+        logger: BackupLogger,
+        debounce_seconds: int,
+    ):
+        """Initialize event handler.
+
+        Args:
+            backup_manager: BackupManager instance
+            state: StateManager instance
+            logger: BackupLogger instance
+            debounce_seconds: Debounce delay in seconds
+        """
+        super().__init__()
+        self.backup_manager = backup_manager
+        self.state = state
+        self.logger = logger
+        self.debounce_seconds = debounce_seconds
+        self.pending_files: dict[Path, float] = {}
+        self.backed_up_count = 0
+
+    def on_modified(self, event: Any) -> None:
+        """Handle file modification event.
+
+        Args:
+            event: File system event
+        """
+        if event.is_directory:
+            return
+
+        file_path = Path(event.src_path)
+
+        # Skip excluded files
+        if BackupManager.matches_exclusion_pattern(file_path.name, self.backup_manager.excluded_patterns):
+            # Find matching pattern for logging
+            for pattern in self.backup_manager.excluded_patterns:
+                if file_path.match(pattern) or (file_path.name.startswith(".") and pattern == ".backup_state.json"):
+                    self.logger.log_file_excluded(file_path.name, pattern)
+                    break
+            return
+
+        # Log modification
+        self.logger.log_file_modified(file_path.name)
+        console.print(f"\n[{datetime.now().strftime('%Y-%m-%d %H:%M:%S')}] File modified: {file_path.name}")
+
+        # Update timestamp for this file (extends debounce window if already pending)
+        self.pending_files[file_path] = time.time()
+
+    def process_pending_files(self) -> None:
+        """Process pending files that have passed the debounce window."""
+        now = time.time()
+        files_to_backup = []
+
+        # Find files that have passed debounce window
+        for file_path, event_time in list(self.pending_files.items()):
+            if now - event_time >= self.debounce_seconds:
+                files_to_backup.append(file_path)
+
+        # Backup files that passed debounce
+        for file_path in files_to_backup:
+            try:
+                # Check if file still exists and is not locked
+                if not file_path.exists():
+                    del self.pending_files[file_path]
+                    continue
+
+                timestamp = datetime.now()
+                backup_path = self.backup_manager.backup_file(file_path, timestamp)
+
+                # Update state
+                self.state.update_file_timestamp(file_path.name, file_path.stat().st_mtime)
+                self.state.save()
+
+                # Log success
+                self.logger.log_file_backed_up(file_path.name, backup_path.name)
+                console.print(f"[{timestamp.strftime('%Y-%m-%d %H:%M:%S')}] Backing up: {file_path.name} -> {backup_path.name} [green]OK[/green]")
+
+                self.backed_up_count += 1
+
+                # Remove from pending
+                del self.pending_files[file_path]
+
+            except PermissionError:
+                self.logger.log_error(f"Permission denied: {file_path.name}")
+                console.print(f"[red]ERROR[/red] Permission denied: {file_path.name}")
+                del self.pending_files[file_path]
+
+            except OSError:
+                self.logger.log_file_locked(file_path.name)
+                console.print(f"[yellow]WARNING[/yellow] File locked, skipping: {file_path.name}")
+                del self.pending_files[file_path]
+
+
+@app.command()
+def watch(
+    source: Path = typer.Option(  # noqa: B008
+        ...,
+        "--source",
+        help="Source directory to monitor",
+        exists=True,
+        file_okay=False,
+        dir_okay=True,
+        resolve_path=True,
+    ),
+    destination: Path = typer.Option(  # noqa: B008
+        ...,
+        "--destination",
+        help="Destination backup directory",
+        file_okay=False,
+        dir_okay=True,
+        resolve_path=True,
+    ),
+    exclude: List[str] = typer.Option(  # noqa: B008
+        [],
+        "--exclude",
+        help="File/directory patterns to exclude (can be repeated)",
+    ),
+    debounce: int = typer.Option(
+        2,
+        "--debounce",
+        help="Seconds to wait after modification before backup",
+        min=0,
+    ),
+) -> None:
+    """Continuously monitor and backup files in real-time.
+
+    This command starts a file system monitor that watches the source directory
+    for changes. When a file is modified, it automatically creates a timestamped
+    backup after a short delay (debounce). The monitor runs until you press
+    Ctrl+C.
+
+    Examples:
+
+      # Basic watch mode
+      trs-file-backup watch --source C:\\Projects\\MyApp --destination C:\\Backup\\MyApp
+
+      # Watch with exclusions
+      trs-file-backup watch --source ./src --destination ./backup --exclude "*.log"
+
+      # Custom debounce delay (5 seconds)
+      trs-file-backup watch --source ./src --destination ./backup --debounce 5
+
+    Tips:
+      - Use Ctrl+C to stop monitoring
+      - Debounce prevents backing up files that are still being written
+      - Hidden directories (starting with .) are automatically excluded
+    """
+    logger = None
+    try:
+        # Add default exclusions
+        excluded_patterns = [".backup_state.json", *exclude]
+
+        # Load or create state
+        state_file = destination / ".backup_state.json"
+        state = StateManager.load(state_file)
+
+        if state is None:
+            # Create new state
+            state = StateManager(
+                source_path=source,
+                destination_path=destination,
+                debounce_seconds=debounce,
+                excluded_patterns=excluded_patterns,
+                files={},
+            )
+        else:
+            # Update state with current parameters
+            state.excluded_patterns = excluded_patterns
+            state.debounce_seconds = debounce
+
+        # Save state
+        state.save()
+
+        # Create logger
+        logger = BackupLogger(destination)
+
+        # Log session start
+        logger.log_session_start(
+            command="watch",
+            source_path=source,
+            destination_path=destination,
+            excluded_patterns=excluded_patterns,
+            debounce_seconds=debounce,
+        )
+        logger.log_watch_started()
+
+        # Create backup manager
+        backup_manager = BackupManager(
+            source_path=source,
+            destination_path=destination,
+            excluded_patterns=excluded_patterns,
+            state=state,
+        )
+
+        # Create event handler
+        event_handler = BackupEventHandler(
+            backup_manager=backup_manager,
+            state=state,
+            logger=logger,
+            debounce_seconds=debounce,
+        )
+
+        # Start observer
+        observer = Observer()
+        observer.schedule(event_handler, str(source), recursive=False)
+        observer.start()
+
+        console.print(f"[green]Starting file system monitor for {source}[/green]")
+        console.print("Watching for changes... (Press Ctrl+C to stop)")
+        console.print(f"Logging to: {destination / 'backup.log'}\n")
+
+        try:
+            while True:
+                # Check for pending files to backup
+                event_handler.process_pending_files()
+                time.sleep(0.5)  # Check every 0.5 seconds
+        except KeyboardInterrupt:
+            observer.stop()
+            logger.log_watch_stopped()
+            logger.log_session_end(event_handler.backed_up_count, event_handler.backed_up_count)
+
+            console.print("\n\nCtrl+C detected. Stopping file system monitor...")
+
+        observer.join()
+
+    except Exception as e:
+        console.print(f"[red]Error:[/red] {e}")
+        raise typer.Exit(code=1) from None
+    finally:
+        if logger is not None:
+            logger.close()
+
+
+if __name__ == "__main__":
+    app()

trs_file_backup/state.py

@@ -0,0 +1,122 @@
+"""State management for backup operations."""
+
+import json
+from pathlib import Path
+from typing import Dict, List, Optional
+
+
+class StateManager:
+    """Manages the backup state including file timestamps and configuration."""
+
+    def __init__(
+        self,
+        source_path: Path,
+        destination_path: Path,
+        debounce_seconds: int,
+        excluded_patterns: List[str],
+        files: Dict[str, float],
+    ):
+        """Initialize state manager.
+
+        Args:
+            source_path: Source directory path
+            destination_path: Destination directory path
+            debounce_seconds: Debounce delay in seconds
+            excluded_patterns: List of exclusion patterns
+            files: Dictionary mapping filenames to their last backup timestamps
+        """
+        self.source_path = source_path
+        self.destination_path = destination_path
+        self.debounce_seconds = debounce_seconds
+        self.excluded_patterns = excluded_patterns
+        self.files = files
+
+    @property
+    def state_file_path(self) -> Path:
+        """Get the path to the state file.
+
+        Returns:
+            Path to .backup_state.json in destination directory
+        """
+        return self.destination_path / ".backup_state.json"
+
+    @classmethod
+    def load(cls, state_file_path: str | Path) -> Optional["StateManager"]:
+        """Load state from file.
+
+        Args:
+            state_file_path: Path to the state file
+
+        Returns:
+            StateManager instance if file exists, None otherwise
+
+        Raises:
+            json.JSONDecodeError: If state file contains invalid JSON
+        """
+        path = Path(state_file_path)
+        if not path.exists():
+            return None
+
+        with open(path, encoding="utf-8") as f:
+            data = json.load(f)
+
+        return cls(
+            source_path=Path(data["source_path"]),
+            destination_path=Path(data["destination_path"]),
+            debounce_seconds=data["debounce_seconds"],
+            excluded_patterns=data["excluded_patterns"],
+            files=data["files"],
+        )
+
+    def save(self) -> None:
+        """Save state to file using atomic write operation.
+
+        Creates destination directory if it doesn't exist.
+        Uses temp file + rename for atomic write.
+        """
+        # Ensure destination directory exists
+        self.destination_path.mkdir(parents=True, exist_ok=True)
+
+        # Prepare data
+        data = {
+            "source_path": str(self.source_path),
+            "destination_path": str(self.destination_path),
+            "log_file": "backup.log",
+            "debounce_seconds": self.debounce_seconds,
+            "excluded_patterns": self.excluded_patterns,
+            "files": self.files,
+        }
+
+        # Write to temp file first (atomic operation)
+        import os
+
+        temp_file = self.state_file_path.with_suffix(".json.tmp")
+        with open(temp_file, "w", encoding="utf-8") as f:
+            json.dump(data, f, indent=2)
+
+        # Rename temp file to actual file (atomic on most filesystems)
+        # Use os.replace for cross-platform atomic replacement
+        os.replace(str(temp_file), str(self.state_file_path))
+
+    def update_file_timestamp(self, filename: str, timestamp: float) -> None:
+        """Update or add file timestamp.
+
+        Args:
+            filename: Name of the file
+            timestamp: Modification timestamp
+        """
+        self.files[filename] = timestamp
+
+    def is_modified(self, filename: str, current_timestamp: float) -> bool:
+        """Check if file is modified since last backup.
+
+        Args:
+            filename: Name of the file
+            current_timestamp: Current modification timestamp
+
+        Returns:
+            True if file is new or modified, False otherwise
+        """
+        if filename not in self.files:
+            return True
+        return current_timestamp > self.files[filename]

trs_file_backup-2.0.1.dist-info/METADATA

@@ -0,0 +1,98 @@
+Metadata-Version: 2.4
+Name: trs-file-backup
+Version: 2.0.1
+Summary: Script to backup changed files in a given folder.
+Author: Ruediger Reiner
+License: MIT
+License-File: LICENSE
+Requires-Python: >=3.10
+Requires-Dist: py-app-dev>=2.6
+Requires-Dist: rich>=13.7
+Requires-Dist: typer>=0.16
+Requires-Dist: watchdog>=4.0
+Description-Content-Type: text/markdown
+
+# trs-file-backup
+
+**trs-file-backup** automatically watches your working directories and creates timestamped backups of every changed file — purely local, no cloud, no sync service, no complex setup. Ideal for developers and creators who want a simple safety net while working on files that are not (yet) in version control.
+
+![maintained](https://img.shields.io/badge/maintained-yes-success?style=flat-square)
+![license](https://img.shields.io/badge/license-MIT-009b9b?style=flat-square)
+![PyPI](https://img.shields.io/pypi/v/trs-file-backup?style=flat-square)
+![Python](https://img.shields.io/pypi/pyversions/trs-file-backup?style=flat-square)
+![ruff](https://img.shields.io/endpoint?url=https://raw.githubusercontent.com/astral-sh/ruff/main/assets/badge/v2.json)
+![uv](https://img.shields.io/endpoint?url=https://raw.githubusercontent.com/astral-sh/uv/main/assets/badge/v0.json)
+[![Build Status](https://github.com/TheRedSwabian/trs-file-backup/actions/workflows/ci.yml/badge.svg?branch=develop)](https://github.com/TheRedSwabian/trs-file-backup/actions)
+[![codecov](https://codecov.io/gh/TheRedSwabian/trs-file-backup/branch/develop/graph/badge.svg)](https://codecov.io/gh/TheRedSwabian/trs-file-backup)
+
+## Requirements
+
+- **Python** 3.10 or higher
+- **OS**: Windows, Linux, macOS
+
+## Features
+
+- 📁 **Top-Level Monitoring** *(subdirectory support planned)*: Monitors files directly in the source directory
+- 📦 **Flat Backup Structure**: All backups stored in one directory for easy access
+- 🔄 **Incremental Backups**: Only backup files that have changed
+- 🕐 **Timestamped Files**: Each backup uses format `filename_YYYY_MM_DD__HH_MM_SS.ext`
+- 👁️ **Watch Mode**: Continuously monitor directories and backup automatically
+- ⏱️ **Configurable Debounce**: Adjustable delay before backup (default: 2 seconds)
+- 🎯 **Smart Exclusions**: Automatically skip hidden files
+- 🚫 **Custom Patterns**: Exclude specific files with wildcard patterns
+- 📊 **State Tracking**: Maintain backup history in `.backup_state.json` (stored in backup directory)
+- 📝 **Activity Logging**: All operations logged to `backup.log` with timestamps
+- 🔍 **Dry-Run Mode**: Preview changes before backing up
+
+## Quick Start
+
+### Installation
+
+Install this via pip (or your favorite package manager):
+
+```bash
+pip install trs-file-backup
+```
+
+### Basic Usage
+
+```bash
+# Initialize backup tracking
+trs-file-backup init --source ./myproject --destination ./backup
+
+# One-time backup of modified files
+trs-file-backup run --source ./myproject --destination ./backup
+
+# Continuous monitoring (watch mode)
+trs-file-backup watch --source ./myproject --destination ./backup
+
+# Exclude specific patterns
+trs-file-backup run --source ./myproject --destination ./backup --exclude "*.log" --exclude "temp_*"
+
+# Custom debounce delay (wait 5 seconds before backup)
+trs-file-backup run --source ./myproject --destination ./backup --debounce 5
+
+# Preview without copying
+trs-file-backup run --source ./myproject --destination ./backup --dry-run
+
+# Get help
+trs-file-backup --help
+trs-file-backup run --help
+```
+
+### Example Output
+
+Original file: `report.txt`
+Backup file: `report_2026_01_13__14_30_22.txt`
+
+## Commands
+
+- **`init`**: Initialize backup tracking for a directory
+- **`run`**: Execute a one-time backup of modified files
+- **`watch`**: Continuously monitor and backup files in real-time
+
+Use `trs-file-backup COMMAND --help` for detailed information on each command.
+
+## Contributing
+
+Contributions are welcome! See [CONTRIBUTING.md](CONTRIBUTING.md) for setup instructions, commit conventions, and the release process.

trs_file_backup-2.0.1.dist-info/RECORD

@@ -0,0 +1,11 @@
+trs_file_backup/__init__.py,sha256=wAxkK8w13vqoF47A8iqWdSlIgRRXmZiQ0R4wePZfzhs,22
+trs_file_backup/backup.py,sha256=X9x3U1jRvrSBpvNA7iNGbl0FVQpoTs-zRD7Hmz5LPWU,4184
+trs_file_backup/logger.py,sha256=mGZlfQpPpK8QIWduZCzaj5aGI224cTtpBQahcNtjOws,5637
+trs_file_backup/main.py,sha256=Drr0wCo01jAiAWiog2B_z775TywbUht4JaOPw_XbPdE,18808
+trs_file_backup/py.typed,sha256=47DEQpj8HBSa-_TImW-5JCeuQeRkm5NMpJWZG3hSuFU,0
+trs_file_backup/state.py,sha256=FGTc1MoG4DaqAJf2Vow3ko-b8SK3oE9tpJrtn2uGfZg,4047
+trs_file_backup-2.0.1.dist-info/METADATA,sha256=YRI4LGw5KJVT2lVU0IzPt8NcaQrRMrKOaELeRCmKgMQ,3980
+trs_file_backup-2.0.1.dist-info/WHEEL,sha256=mffPy8wBnZQn2VnJUU5jE99KsxaSfiyMHV9Yt0aLVxs,87
+trs_file_backup-2.0.1.dist-info/entry_points.txt,sha256=jLDNVyqWd8_qjX_kEagbxP2lOB0DZd_2AmMlB9_RgCw,92
+trs_file_backup-2.0.1.dist-info/licenses/LICENSE,sha256=LzV1Ewc6B77-EaOwzSlvTtF23k8o7HSaSQ_9Y3dZlv8,1072
+trs_file_backup-2.0.1.dist-info/RECORD,,

trs_file_backup-2.0.1.dist-info/WHEEL

@@ -0,0 +1,4 @@
+Wheel-Version: 1.0
+Generator: hatchling 1.30.1
+Root-Is-Purelib: true
+Tag: py3-none-any

trs_file_backup-2.0.1.dist-info/entry_points.txt

@@ -0,0 +1,3 @@
+[console_scripts]
+bcs = trs_file_backup.main:app
+trs-file-backup = trs_file_backup.main:app

trs_file_backup-2.0.1.dist-info/licenses/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Ruediger Reiner
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.