From 4f27c895fdb0220e675fb03cf26408607b82f816 Mon Sep 17 00:00:00 2001 From: bartool Date: Fri, 6 Mar 2026 20:09:04 +0100 Subject: [PATCH] docs: finalize gemini.md with implementation details and build instructions --- gemini.md | 472 +++++------------------------------------------------- 1 file changed, 38 insertions(+), 434 deletions(-) diff --git a/gemini.md b/gemini.md index 2a62d25..6ec3ea9 100644 --- a/gemini.md +++ b/gemini.md @@ -1,457 +1,61 @@ -# gemini.md +# Project Status: Completed -## Project Overview - -This project is a **Windows background application written in Python** that automatically monitors a selected **Git repository directory** and performs commits whenever files change. - -The application is intended for environments where users are **not expected to interact with Git manually** (e.g. CNC operators). All commits are handled automatically. - -The application runs **silently in the background** with a **system tray icon** and **Windows notifications**. - -The final application must be packaged using **PyInstaller as a single executable file** with **no console window**. +The application is fully implemented and tested for Windows 11 background operation. --- -# Core Features +# Current Architecture (Finalized) -## Background Operation - -* The application runs in the background. -* No console window should be visible. -* A **system tray icon** must be present in the Windows taskbar notification area. - -The tray icon menu must contain: - -* **Select Repository Folder** -* **Exit Application** - ---- - -# Git Monitoring Behavior - -The application monitors a selected folder that contains a **Git repository**. - -Every filesystem change triggers an automatic commit. - -The following actions must be detected: - -* File created -* File modified -* File deleted -* File renamed / moved - -Each change should produce a commit with message: +The project is structured as a proper Python package to ensure compatibility with PyInstaller and robust path handling. ``` -f"{action}: {file}" -``` - -Examples: - -``` -create: program.nc -modify: toolpath.nc -delete: old_part.nc -rename: part_v1.nc -> part_v2.nc -``` - -Commits must be executed automatically using Git. - -If the directory is not a Git repository, the application should: - -* notify the user -* not start monitoring - ---- - -# Windows Notifications - -The application should generate **Windows toast notifications** for: - -* repository monitoring started -* repository monitoring stopped -* commit created -* errors - -Example notification: - -``` -Git Monitor -modify: program.nc committed +auto-git/ +├── run.py # Main entry point for Python/PyInstaller +├── git_monitor/ # Main package +│ ├── __init__.py # Package marker +│ ├── main.py # Application lifecycle +│ ├── tray_app.py # System tray (pystray) + UI (tkinter) +│ ├── git_manager.py # Git operations (GitPython) +│ ├── file_watcher.py # Filesystem monitoring (watchdog) +│ ├── notifier.py # Windows notifications (plyer + win10toast fallback) +│ ├── config.py # Persistent configuration (config.json) +│ ├── logger.py # Application logging (git_monitor.log) +│ └── requirements.txt # Dependency list +└── .gitignore # Project ignore rules ``` --- -# Logging +# Implemented Solutions & Fixes -The application must write logs to a file. +### 1. UI Responsive Fix (Windows 11) +To prevent the application from freezing during folder selection: +* **Threading**: `pystray` runs in a separate background thread. +* **Main Loop**: `tkinter.mainloop()` runs in the main thread to handle system dialogs properly. +* **Non-blocking Dialogs**: Folder selection is scheduled via `root.after(0, ...)` to ensure it doesn't block the tray icon. -Log file requirements: - -* log filename: `git_monitor.log` -* stored in the application directory -* log levels: - - * INFO - * WARNING - * ERROR - -Logged events: - -* application start -* repository selected -* detected file change -* git commit executed -* errors and exceptions +### 2. PyInstaller Compatibility +* **Package Imports**: All internal imports use absolute paths (e.g., `from git_monitor.logger import ...`). +* **Path Management**: `logger.py` and `config.py` use `sys.frozen` detection to ensure data files are always located relative to the `.exe` file, not temporary directories. +* **Notification Robustness**: Added a fallback mechanism in `notifier.py`. If `plyer` fails to find a platform implementation (common in isolated environments), it automatically switches to `win10toast`. --- -# System Tray UI +# Build Instructions -The application must provide a **tray icon**. +To generate the standalone executable, use the following command from the project root: -Right-click menu: - -``` -Git Monitor -──────────── -Select Repository -Exit +```powershell +pyinstaller.exe --onefile --noconsole --name git-monitor --hidden-import="plyer.platforms.win.notification" run.py ``` -Behavior: - -### Select Repository - -Opens a folder selection dialog. - -Once selected: - -* verify `.git` directory exists -* start monitoring - -### Exit - -Stops monitoring and terminates the application. +### Build Parameters: +* `--onefile`: Packages everything into a single `.exe`. +* `--noconsole`: Hides the command prompt window during execution. +* `--hidden-import`: Manually includes the dynamic notification module for Windows. --- -# Application Architecture - -The application must be **modular** and structured using classes. - -Recommended project structure: - -``` -git_monitor/ - -main.py -tray_app.py -git_manager.py -file_watcher.py -notifier.py -config.py -logger.py -``` - ---- - -# Modules - -## main.py - -Application entry point. - -Responsibilities: - -* initialize logging -* initialize tray application -* start event loop - -Main class: - -``` -Application -``` - ---- - -# tray_app.py - -Handles the **system tray icon and menu**. - -Recommended library: - -``` -pystray -``` - -Responsibilities: - -* create tray icon -* handle menu events -* start/stop monitoring - -Main class: - -``` -TrayApp -``` - -Methods: - -``` -select_repository() -start_monitoring() -stop_monitoring() -exit_app() -``` - ---- - -# file_watcher.py - -Responsible for filesystem monitoring. - -Recommended library: - -``` -watchdog -``` - -Main class: - -``` -RepositoryWatcher -``` - -Responsibilities: - -* monitor filesystem events -* translate events to actions -* send events to GitManager - -Handled events: - -``` -on_created -on_modified -on_deleted -on_moved -``` - ---- - -# git_manager.py - -Handles all Git operations. - -Recommended library: - -``` -GitPython -``` - -Main class: - -``` -GitManager -``` - -Responsibilities: - -* validate repository -* stage changed files -* perform commits - -Methods: - -``` -is_git_repository(path) -commit_change(action, file) -``` - -Commit format: - -``` -f"{action}: {file}" -``` - ---- - -# notifier.py - -Responsible for Windows notifications. - -Recommended library: - -``` -win10toast or plyer -``` - -Main class: - -``` -Notifier -``` - -Methods: - -``` -notify(title, message) -``` - ---- - -# logger.py - -Handles application logging. - -Use Python logging module. - -Features: - -* file logging -* timestamp -* log levels - -Log format example: - -``` -2026-03-06 18:32:11 INFO Repository monitoring started -2026-03-06 18:32:20 INFO modify: program.nc committed -``` - ---- - -# config.py - -Stores application configuration. - -Possible stored data: - -* last used repository path - -Config file format: - -``` -config.json -``` - -Example: - -``` -{ - "repository_path": "C:/cnc/programs" -} -``` - ---- - -# Packaging - -The application must be packaged using **PyInstaller**. - -Requirements: - -* single executable -* no console window - -Example build command: - -``` -pyinstaller --onefile --noconsole main.py -``` - ---- - -# Error Handling - -The application must gracefully handle: - -* invalid repository path -* git errors -* filesystem watcher errors -* missing permissions - -Errors must: - -* be logged -* generate a Windows notification - ---- - -# Performance Considerations - -The application should: - -* avoid duplicate commits for rapid file changes -* debounce filesystem events if necessary -* run with minimal CPU usage - ---- - -# Recommended Python Libraries - -``` -watchdog -GitPython -pystray -pillow -win10toast -``` - ---- - -# Example Workflow - -1. Application starts -2. Tray icon appears -3. User selects repository -4. Monitoring begins -5. User edits a file -6. File watcher detects modification -7. GitManager stages file -8. Commit created automatically -9. Notification appears -10. Event logged - ---- - -# Future Improvements - -Possible future features: - -* commit batching -* ignore patterns (.gitignore support) -* commit history viewer -* push to remote repository -* repository auto-detection -* configuration GUI -* multiple repository support - ---- - -# Coding Style - -Requirements: - -* Python 3.11+ -* object-oriented design -* clear class responsibilities -* structured logging -* minimal global state - ---- - -# Summary - -The goal is to create a **lightweight background Windows application** that automatically commits changes in a Git repository without requiring the user to interact with Git. - -The system should be: - -* stable -* silent -* automatic -* easy to deploy (single EXE) -* minimal UI (tray only) +# Runtime Files +* **Log File**: `git_monitor.log` (created in the same folder as the `.exe`). +* **Config File**: `config.json` (created in the same folder as the `.exe`).