clevergit 0.1.0__tar.gz

clevergit-0.1.0/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 petertzy
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

clevergit-0.1.0/MANIFEST.in

@@ -0,0 +1,7 @@
+include README.MD
+include LICENSE
+include pyproject.toml
+recursive-include clevergit *.py
+recursive-exclude tests *
+recursive-exclude * __pycache__
+recursive-exclude * *.py[co]

clevergit-0.1.0/PKG-INFO

@@ -0,0 +1,376 @@
+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.