Metadata-Version: 2.4
Name: clevergit
Version: 0.1.0
Summary: A CleverGit-like Git client tool with high-level abstractions
Author: petertzy
License: MIT
Project-URL: Homepage, https://github.com/petertzy/CleverGit
Project-URL: Repository, https://github.com/petertzy/CleverGit
Project-URL: Issues, https://github.com/petertzy/CleverGit/issues
Keywords: git,version-control,cli,gui,git-client
Classifier: Development Status :: 3 - Alpha
Classifier: Intended Audience :: Developers
Classifier: License :: OSI Approved :: MIT License
Classifier: Programming Language :: Python :: 3
Classifier: Programming Language :: Python :: 3.9
Classifier: Programming Language :: Python :: 3.10
Classifier: Programming Language :: Python :: 3.11
Classifier: Programming Language :: Python :: 3.12
Classifier: Topic :: Software Development :: Version Control :: Git
Requires-Python: >=3.9
Description-Content-Type: text/markdown
License-File: LICENSE
Requires-Dist: GitPython>=3.1.40
Requires-Dist: typer>=0.9.0
Requires-Dist: rich>=13.7.0
Requires-Dist: PySide6>=6.6.0
Requires-Dist: requests>=2.31.0
Provides-Extra: gui
Requires-Dist: PySide6>=6.6.0; extra == "gui"
Provides-Extra: dev
Requires-Dist: pytest>=7.4.0; extra == "dev"
Requires-Dist: pytest-cov>=4.1.0; extra == "dev"
Requires-Dist: black>=23.0.0; extra == "dev"
Requires-Dist: ruff>=0.1.0; extra == "dev"
Requires-Dist: mypy>=1.7.0; extra == "dev"
Dynamic: license-file

# Project Documentation (CleverGit - Git Client, Python Implementation)

## Quick Start

CleverGit provides **two ways to interact** with your Git repositories:

### 🖥️ **Graphical User Interface (GUI)**

Launch the GUI application for an intuitive, visual Git experience:

```bash
sgg
# or
python -m clevergit.ui.main
```

**Features:**
- Point-and-click repository management
- Visual file status display
- Branch management with drag-and-drop
- Commit history viewer
- Dialog-based operations
- **Enhanced Diff Viewer** - Professional, SmartGit-inspired code difference presentation
  - Softer color scheme for reduced eye strain
  - Word-level highlighting to spot exact changes
  - Improved visual spacing and separation
  - Side-by-side and unified views
- **Command Palette** - Quick search and command execution (`Ctrl+P`)
  - Search files, commits, and branches with fuzzy matching
  - Execute commands without navigating menus
  - Keyboard-driven workflow

👉 **For detailed GUI documentation, see [GUI_USAGE.md](GUI_USAGE.md)**

### 💻 **Command Line Interface (CLI)**

Use powerful command-line commands for scriptable Git operations:

```bash
# View repository status
sg status

# Commit all changes
sg commit all -m "feat: add new feature"

# View commit history
sg log --oneline

# Manage branches
sg branch list
sg branch new feature/auth
sg branch switch main
```

**Features:**
- Fast, efficient terminal-based workflow
- Scriptable operations
- Batch processing support
- Integration with other tools

### 🐍 **Python API**

Use CleverGit programmatically in your Python scripts:

```python
from clevergit import Repo

# Open repository
repo = Repo.open(".")

# Check status
status = repo.status()
print(f"Modified files: {len(status.modified)}")

# Create commit
repo.commit_all("fix: resolve issue")

# Branch operations
repo.create_branch("feature/new")
repo.checkout("feature/new")
```

### 📦 Installation

```bash
# Clone the repository
git clone https://github.com/petertzy/CleverGit.git
cd CleverGit

# Install with all features
pip install -e .

# Verify installation
sgg --version  # GUI version check
sg --version   # CLI version check
```

---

## 1. Project Background & Goals

This project aims to develop an advanced Git client tool **CleverGit** using **Python**, with focus on:

* Provide **more user-friendly, higher-level** Git operation abstractions
* Lower the learning curve for daily Git usage (especially complex commands)
* Support **CLI-first, GUI-extensible** architecture design

Target users:

* Developers familiar with Git basics but don't want to memorize commands frequently
* Users who want to operate Git in Python within scripts / toolchains

---

## 2. Design Principles

1. **High-level semantics, not command concatenation**
   Example:

   * `repo.commit_all("fix login bug")`
   * Instead of `git commit -am "..."`

2. **Readability first**
   Class names and method names should express "user intent" rather than Git details

3. **Modular & Extensible**

   * Decouple CLI / GUI / API
   * Can add TUI / Web UI later

4. **Failure is explainable**

   * Convert Git errors to "human-readable" exception messages

---

## 3. Technology Stack

* Python >= 3.10
* Git calling methods:

  * Preferred: `GitPython`
  * Fallback: `subprocess` (for scenarios GitPython doesn't support)
* CLI framework:

  * `typer` (recommended, type-friendly)
* GUI (future):

  * `PySide6` or `Tkinter`

---

## 4. Core Feature Planning

### 4.1 Repository Management

* Open / Initialize repository
* Detect repository status
* Current branch, HEAD status

```text
✔ Is it a Git repository
✔ Are there uncommitted changes
✔ Is it behind / ahead of remote branch
```

---

### 4.2 Status View

* Modified files
* Untracked files
* Staged files
* Conflicted files

Support:

* Group by file type
* Output as structured objects for UI use

---

### 4.3 Commit

* Commit all changes
* Selective commit (specific files)
* Auto-generate commit message (optional)
* Pre-commit checks (lint / test hooks)

---

### 4.4 Branch Management

* List branches (local / remote)
* Create / Delete / Rename branches
* Switch branches
* Display branch relationships (simple DAG)

---

### 4.5 Merge & Rebase (High-level Wrapper)

* Safe merge (detect conflicts)
* Interactive rebase workflow (step-by-step)
* Conflict file list + hints

---

### 4.6 Remote Repository Operations

* fetch / pull / push
* Show commits to be pushed / pulled
* force push risk warning

---

### 4.7 History (Log)

* Concise log view (like `git log --oneline --graph`)
* Filter by author / time / branch
* Single commit details

---

## 5. Project File Structure (Recommended)

```text
clevergit/
├── README.md
├── pyproject.toml
├── clevergit/
│   ├── __init__.py
│   ├── core/                  # Core Git logic
│   │   ├── repo.py             # Repository object (core entry point)
│   │   ├── status.py           # Status analysis
│   │   ├── commit.py           # Commit logic
│   │   ├── branch.py           # Branch management
│   │   ├── merge.py            # merge / rebase
│   │   ├── remote.py           # fetch / pull / push
│   │   └── log.py              # History records
│   │
│   ├── git/                    # Git adapter layer
│   │   ├── client.py           # GitPython / subprocess wrapper
│   │   └── errors.py           # Git errors → business exceptions
│   │
│   ├── cli/                    # CLI layer
│   │   ├── app.py              # Typer entry point
│   │   ├── repo_cmd.py
│   │   ├── commit_cmd.py
│   │   └── branch_cmd.py
│   │
│   ├── ui/                     # GUI / TUI (reserved)
│   │   └── __init__.py
│   │
│   ├── models/                 # Domain models (DTO)
│   │   ├── file_status.py
│   │   ├── commit_info.py
│   │   └── branch_info.py
│   │
│   └── utils/
│       ├── formatter.py        # Output formatting
│       └── helpers.py
│
└── tests/
    ├── test_repo.py
    ├── test_status.py
    └── test_commit.py
```

---

## 6. Core Object Design Example

### Repo (Core Entry Point)

```python
repo = Repo.open(".")

repo.status()
repo.commit_all("fix: login bug")
repo.create_branch("feature/auth")
repo.checkout("feature/auth")
```

Design goals:

* **One Repo object = One Git repository**
* Most features start from here

---

## 7. CLI Design Example

```bash
sg status
sg commit -m "fix bug"
sg branch new feature/auth
sg branch switch main
sg log --oneline
```

CLI principles:

* Short commands
* Don't require users to understand Git detail parameters

---

## 8. Error Handling Strategy

* Git raw errors → Custom exceptions
* CLI layer catches exceptions → User-friendly hints

Example:

```text
❌ Current branch has uncommitted changes, cannot switch branches
Suggestions:
- Commit changes
- Or use sg stash
```

---

## 9. Future Expansion Directions

* GUI (graphical interface)
* AI assistance:

  * Auto-generate commit messages
  * Conflict resolution suggestions
* Plugin system (hooks)
* Git Flow / Trunk Based workflow support

---

## 10. One-Sentence Project Summary

> Wrap Git's "intent layer" in Python, make Git usable like objects, not remembered like incantations.
