bartool/auto-git
1
0
Fork 0
Code Issues Pull Requests Actions Packages Projects Releases Wiki Activity

docs: finalize gemini.md with implementation details and build instructions

Browse Source
This commit is contained in:
bartool
2026-03-06 20:09:04 +01:00
parent e1f8ee95da
commit 4f27c895fd
1 changed files with 38 additions and 434 deletions
Download Patch File Download Diff File Expand all files Collapse all files

472
gemini.md
View File

@@ -1,457 +1,61 @@
# gemini.md # Project Status: Completed
## Project Overview The application is fully implemented and tested for Windows 11 background operation.
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 # Current Architecture (Finalized)
## Background Operation The project is structured as a proper Python package to ensure compatibility with PyInstaller and robust path handling.
* 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}" auto-git/
``` ├── run.py # Main entry point for Python/PyInstaller
├── git_monitor/ # Main package
Examples: │ ├── __init__.py # Package marker
│ ├── main.py # Application lifecycle
``` │ ├── tray_app.py # System tray (pystray) + UI (tkinter)
create: program.nc │ ├── git_manager.py # Git operations (GitPython)
modify: toolpath.nc │ ├── file_watcher.py # Filesystem monitoring (watchdog)
delete: old_part.nc │ ├── notifier.py # Windows notifications (plyer + win10toast fallback)
rename: part_v1.nc -> part_v2.nc │ ├── config.py # Persistent configuration (config.json)
``` │ ├── logger.py # Application logging (git_monitor.log)
│ └── requirements.txt # Dependency list
Commits must be executed automatically using Git. └── .gitignore # Project ignore rules
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 # 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: ### 2. PyInstaller Compatibility
* **Package Imports**: All internal imports use absolute paths (e.g., `from git_monitor.logger import ...`).
* log filename: `git_monitor.log` * **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.
* stored in the application directory * **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`.
* log levels:
* INFO
* WARNING
* ERROR
Logged events:
* application start
* repository selected
* detected file change
* git commit executed
* errors and exceptions
--- ---
# 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: ```powershell
pyinstaller.exe --onefile --noconsole --name git-monitor --hidden-import="plyer.platforms.win.notification" run.py
```
Git Monitor
────────────
Select Repository
Exit
``` ```
Behavior: ### Build Parameters:
* `--onefile`: Packages everything into a single `.exe`.
### Select Repository * `--noconsole`: Hides the command prompt window during execution.
* `--hidden-import`: Manually includes the dynamic notification module for Windows.
Opens a folder selection dialog.
Once selected:
* verify `.git` directory exists
* start monitoring
### Exit
Stops monitoring and terminates the application.
--- ---
# Application Architecture # Runtime Files
* **Log File**: `git_monitor.log` (created in the same folder as the `.exe`).
The application must be **modular** and structured using classes. * **Config File**: `config.json` (created in the same folder as the `.exe`).
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)