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.

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"
}

---

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)