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