7.1 KiB
gemini.md
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.
Core Features
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:
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
# Logging
The application must write logs to a file.
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
---
# System Tray UI
The application must provide a **tray icon**.
Right-click menu:
Git Monitor ──────────── Select Repository Exit
Behavior:
### Select Repository
Opens a folder selection dialog.
Once selected:
* verify `.git` directory exists
* start monitoring
### Exit
Stops monitoring and terminates the application.
---
# 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" }
# Project Status: Completed
The application is fully implemented and tested for Windows 11 background operation.
---
# Current Architecture (Finalized)
The project is structured as a proper Python package to ensure compatibility with PyInstaller and robust path handling.
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
---
# Implemented Solutions & Fixes
### 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.
### 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`.
---
# Build Instructions
To generate the standalone executable, use the following command from the project root:
```powershell
pyinstaller.exe --onefile --noconsole --name git-monitor --hidden-import="plyer.platforms.win.notification" run.py
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.
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).