auto-git/gemini.md

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: ...

rename: part_v1.nc -> part_v2.nc

Git Operations

Commits must be executed automatically using Git. ...

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:

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).