增加跨平台兼容性
This commit is contained in:
334
AGENTS.md
Normal file
334
AGENTS.md
Normal file
@@ -0,0 +1,334 @@
|
||||
# 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
|
||||
Reference in New Issue
Block a user