335 lines
9.3 KiB
Markdown
335 lines
9.3 KiB
Markdown
# Agent Guidelines for QuickGit
|
||
|
||
This document provides coding agents with essential information about the QuickGit codebase, including build commands, code style, and architectural conventions.
|
||
|
||
---
|
||
|
||
## Project Overview
|
||
|
||
**QuickGit** is a modular CLI Git management tool written in Python 3.6+. It simplifies Git operations through an interactive menu system with colorful console output.
|
||
|
||
**Key Technologies:**
|
||
- Pure Python 3.6+ (no external dependencies)
|
||
- Standard library only: `subprocess`, `os`, `datetime`, `sys`
|
||
- Cross-platform support: Windows, Linux, macOS
|
||
- ANSI escape codes for colorful console output
|
||
|
||
---
|
||
|
||
## Build, Run, and Test Commands
|
||
|
||
### Running the Application
|
||
|
||
```bash
|
||
# Recommended: Run the modular version
|
||
python quickgit.py # Windows
|
||
python3 quickgit.py # Linux/macOS
|
||
|
||
# Platform-specific launchers:
|
||
run.bat # Windows (sets UTF-8 encoding)
|
||
./run.sh # Linux/macOS (first run: chmod +x run.sh)
|
||
|
||
# Legacy: Run the single-file version
|
||
python mengya_git_manager.py
|
||
```
|
||
|
||
### Testing
|
||
|
||
**No formal test suite exists yet.** Manual testing workflow:
|
||
|
||
1. **Test in a clean directory:**
|
||
```bash
|
||
cd /path/to/test/directory
|
||
python E:\SmyProjects\Python\脚本\萌芽一键Git管理\quickgit.py
|
||
```
|
||
|
||
2. **Test each menu option:**
|
||
- Option 1: Initialize Git repo
|
||
- Option 2: Commit and push (requires changes)
|
||
- Option 3: Pull from remote
|
||
- Option 4: View status
|
||
- Option 5: Manage remotes
|
||
- Option 6: Exit
|
||
|
||
3. **Verify console output:**
|
||
- Check colors render correctly
|
||
- Ensure ASCII dividers align (60 chars wide)
|
||
- No encoding errors with Chinese characters
|
||
|
||
### Linting and Code Quality
|
||
|
||
```bash
|
||
# No formal linting configured yet
|
||
# Recommended tools for future use:
|
||
# pip install pylint black mypy
|
||
|
||
# Type checking (Python 3.10+ syntax used):
|
||
# mypy quickgit/
|
||
|
||
# Formatting:
|
||
# black quickgit/ --line-length 100
|
||
|
||
# Linting:
|
||
# pylint quickgit/
|
||
```
|
||
|
||
---
|
||
|
||
## Code Style Guidelines
|
||
|
||
### File Organization
|
||
|
||
**Module Structure:**
|
||
```
|
||
quickgit/
|
||
├── __init__.py # Package init (empty)
|
||
├── config.py # Configuration constants
|
||
├── utils.py # Utilities (Colors, CommandExecutor, OutputFormatter, InputValidator, PlatformUtils)
|
||
├── git_operations.py # Git command wrapper
|
||
├── remote_manager.py # Remote repository management
|
||
└── ui.py # User interface and menu system
|
||
```
|
||
|
||
**Principle:** Each module has a single, well-defined responsibility.
|
||
|
||
### Import Conventions
|
||
|
||
**Order:**
|
||
1. Standard library imports
|
||
2. Relative imports from `quickgit` package
|
||
|
||
**Style:**
|
||
```python
|
||
# Standard library
|
||
import os
|
||
import sys
|
||
from datetime import datetime
|
||
|
||
# Internal modules (relative imports preferred)
|
||
from .utils import CommandExecutor, OutputFormatter, Colors
|
||
from .config import Config
|
||
```
|
||
|
||
**Lazy imports for circular dependency avoidance:**
|
||
```python
|
||
def some_function():
|
||
from .utils import Colors # Import inside function if needed
|
||
print(f"{Colors.CYAN}Message{Colors.ENDC}")
|
||
```
|
||
|
||
### Type Hints
|
||
|
||
**Required for all function signatures:**
|
||
|
||
```python
|
||
# Good
|
||
def run(command: str, show_output: bool = True) -> tuple[bool, str]:
|
||
"""Execute command and return (success, output)"""
|
||
pass
|
||
|
||
def get_remotes(self) -> list[str]:
|
||
"""Get all remote repositories"""
|
||
pass
|
||
|
||
def confirm(prompt: str, default: bool = False) -> bool:
|
||
"""Get user confirmation"""
|
||
pass
|
||
```
|
||
|
||
**Note:** Uses Python 3.10+ syntax (`list[str]`, `tuple[bool, str]`). For Python 3.6-3.9 compatibility, use:
|
||
```python
|
||
from typing import List, Tuple
|
||
def get_remotes(self) -> List[str]: ...
|
||
```
|
||
|
||
### Naming Conventions
|
||
|
||
- **Classes:** `PascalCase` (e.g., `GitOperations`, `RemoteManager`)
|
||
- **Functions/Methods:** `snake_case` (e.g., `add_github_remote`, `show_main_menu`)
|
||
- **Constants:** `UPPER_SNAKE_CASE` (e.g., `DEFAULT_BRANCH`, `GITEA_HOST`)
|
||
- **Private methods:** Prefix with `_` (e.g., `_create_gitignore`, `_add_remote`)
|
||
- **Module-level:** Avoid global variables; use `Config` class for constants
|
||
|
||
### Formatting and Whitespace
|
||
|
||
- **Line length:** Aim for 100 characters max (not strictly enforced)
|
||
- **Indentation:** 4 spaces (no tabs)
|
||
- **Blank lines:** 2 between top-level definitions, 1 between methods
|
||
- **Strings:** Use double quotes `"` for user-facing text, either for code strings
|
||
|
||
### Error Handling
|
||
|
||
**Always provide user-friendly feedback:**
|
||
|
||
```python
|
||
# Good
|
||
try:
|
||
with open('.gitignore', 'w', encoding='utf-8') as f:
|
||
f.write(Config.GITIGNORE_TEMPLATE)
|
||
OutputFormatter.success(".gitignore文件创建成功")
|
||
except Exception as e:
|
||
OutputFormatter.error(f".gitignore文件创建失败: {str(e)}")
|
||
```
|
||
|
||
**Command execution pattern:**
|
||
|
||
```python
|
||
success, output = self.executor.run("git status", show_output=False)
|
||
if success:
|
||
OutputFormatter.success("操作成功")
|
||
else:
|
||
OutputFormatter.error("操作失败")
|
||
return False
|
||
```
|
||
|
||
**Never swallow exceptions silently.** Always log errors via `OutputFormatter.error()`.
|
||
|
||
---
|
||
|
||
## Console Output Guidelines
|
||
|
||
### Critical Rules
|
||
|
||
1. **NO EMOJI CHARACTERS** - They cause Windows console encoding errors
|
||
2. **NO UNICODE BOX-DRAWING** (`┌─┐│└┘╔═╗║╚╝`) - They misalign across terminals
|
||
3. **Use ASCII only:** `=`, `-`, `·` for dividers
|
||
4. **Status indicators:** `[√]`, `[×]`, `[i]`, `[!]`, `[>]` instead of Unicode symbols
|
||
5. **Fixed width:** All dividers are exactly 60 characters wide
|
||
|
||
### Color Usage
|
||
|
||
**Color scheme:**
|
||
```python
|
||
Colors.BRIGHT_GREEN # Success messages
|
||
Colors.BRIGHT_RED # Errors
|
||
Colors.BRIGHT_CYAN # Info/prompts
|
||
Colors.BRIGHT_YELLOW # Warnings/section headers
|
||
Colors.BRIGHT_MAGENTA # Main headers
|
||
Colors.WHITE # General text
|
||
```
|
||
|
||
**Always reset colors:**
|
||
```python
|
||
print(f"{Colors.BRIGHT_GREEN}Success{Colors.ENDC}") # ENDC resets to default
|
||
```
|
||
|
||
### Output Formatting Functions
|
||
|
||
```python
|
||
OutputFormatter.header("Title") # Top-level header (cyan/magenta)
|
||
OutputFormatter.section("Section") # Section header (yellow/blue)
|
||
OutputFormatter.divider() # 60-char line: ----------
|
||
OutputFormatter.success("Done!") # [√] Green success
|
||
OutputFormatter.error("Failed!") # [×] Red error
|
||
OutputFormatter.info("Note...") # [i] Cyan info
|
||
OutputFormatter.warning("Warning!") # [!] Yellow warning
|
||
OutputFormatter.step(1, "Step one") # [1] Step indicator
|
||
OutputFormatter.menu_item(1, "Option") # [1] Menu item
|
||
```
|
||
|
||
---
|
||
|
||
## Git Operations Patterns
|
||
|
||
### SSH Configuration
|
||
|
||
- **GitHub:** `git@github.com:shumengya/{repo}.git`
|
||
- **Gitea:** `ssh://git@repo.shumengya.top:8022/{user}/{repo}.git`
|
||
|
||
All remote operations use SSH (no HTTPS).
|
||
|
||
### Command Execution
|
||
|
||
**Pattern for all Git commands:**
|
||
|
||
```python
|
||
# 1. Show status indicator
|
||
OutputFormatter.status('running', "Pushing to remote...")
|
||
|
||
# 2. Execute command (capture output)
|
||
success, output = self.executor.run("git push origin main", show_output=True)
|
||
|
||
# 3. Provide feedback
|
||
if success:
|
||
OutputFormatter.success("Push successful")
|
||
else:
|
||
OutputFormatter.error("Push failed")
|
||
|
||
return success
|
||
```
|
||
|
||
---
|
||
|
||
## Adding New Features
|
||
|
||
### Checklist for New Functionality
|
||
|
||
1. **Determine the module:** Where does this feature belong?
|
||
- Git operations → `git_operations.py`
|
||
- Remote management → `remote_manager.py`
|
||
- UI/menus → `ui.py`
|
||
- Config/constants → `config.py`
|
||
- Utilities → `utils.py`
|
||
|
||
2. **Add type hints** to all functions
|
||
|
||
3. **Use OutputFormatter** for all user-facing messages
|
||
|
||
4. **Test manually** in a clean directory
|
||
|
||
5. **Update README.md** if adding user-facing features
|
||
|
||
---
|
||
|
||
## Common Gotchas
|
||
|
||
1. **Windows path handling:** Use `os.path` or `pathlib` for cross-platform paths
|
||
2. **Encoding:** All file I/O must specify `encoding='utf-8'`
|
||
3. **Subprocess:** Always use `encoding='utf-8', errors='ignore'` in `subprocess.run()`
|
||
4. **Git output:** Some commands have localized output; parse carefully
|
||
5. **Empty commits:** Check `git status --short` before committing
|
||
6. **Divider width:** Always use exactly 60 characters for consistency
|
||
7. **Platform differences:**
|
||
- Use `python3` on Linux/macOS, `python` on Windows
|
||
- Shell scripts: `.sh` for Unix, `.bat` for Windows
|
||
- Clear screen: Use `PlatformUtils.clear_screen()` for cross-platform support
|
||
|
||
---
|
||
|
||
## Platform-Specific Notes
|
||
|
||
### Windows
|
||
- Use `run.bat` launcher to set UTF-8 encoding (`chcp 65001`)
|
||
- ANSI colors supported on Windows 10+ by default
|
||
- Python command: `python` (not `python3`)
|
||
|
||
### Linux/macOS
|
||
- Use `run.sh` launcher (requires `chmod +x run.sh` first time)
|
||
- Ensure terminal supports UTF-8 encoding
|
||
- Python command: `python3` (not `python`)
|
||
- Shell uses bash (shebang: `#!/bin/bash`)
|
||
|
||
### Cross-Platform Code
|
||
- Use `PlatformUtils.is_windows()`, `is_linux()`, `is_mac()` for platform detection
|
||
- Use `PlatformUtils.clear_screen()` instead of `os.system('cls')` or `os.system('clear')`
|
||
- Always use `os.path.join()` or `pathlib.Path` for file paths
|
||
|
||
---
|
||
|
||
## Future Development Notes
|
||
|
||
**Planned features (not yet implemented):**
|
||
- Branch management
|
||
- Tag management
|
||
- Conflict resolution assistance
|
||
- Custom configuration file support
|
||
- Batch operations for multiple repositories
|
||
- Formal test suite (pytest recommended)
|
||
- CI/CD pipeline
|
||
|
||
**When implementing these:**
|
||
- Follow the existing modular architecture
|
||
- Add to appropriate module (or create new module if needed)
|
||
- Maintain the colorful, user-friendly console output style
|
||
- Keep Windows compatibility in mind
|