392 lines
7.2 KiB
Markdown
392 lines
7.2 KiB
Markdown
# 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.
|
|
|
|
### .gitignore Support
|
|
The application respects `.gitignore` rules of the repository. Files matched by ignore rules will not trigger any actions or commits.
|
|
|
|
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
|
|
```
|
|
|
|
### Git Operations
|
|
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`).
|