123 lines
4.6 KiB
Markdown
123 lines
4.6 KiB
Markdown
# CLAUDE.md
|
|
|
|
This file provides guidance to Claude Code (claude.ai/code) when working with code in this repository.
|
|
|
|
## Project Overview
|
|
|
|
QuickGit (萌芽一键Git管理工具) is a Python CLI tool that simplifies Git operations through an interactive menu interface. It supports managing multiple Git repositories, handles both GitHub and Gitea remotes, and provides cross-platform compatibility (Windows, Linux, macOS).
|
|
|
|
## Running the Application
|
|
|
|
**Windows:**
|
|
```bash
|
|
run.bat # Recommended - sets UTF-8 encoding
|
|
python quickgit.py # Direct execution
|
|
```
|
|
|
|
**Linux/macOS:**
|
|
```bash
|
|
./run.sh # Recommended (requires chmod +x run.sh first time)
|
|
python3 quickgit.py # Direct execution
|
|
```
|
|
|
|
The tool is interactive - no command-line arguments needed. On startup, it prompts for a Git repository directory to manage.
|
|
|
|
## Architecture
|
|
|
|
The codebase follows a modular design with clear separation of concerns:
|
|
|
|
### Module Hierarchy
|
|
|
|
```
|
|
quickgit.py (entry point)
|
|
└── ui.py (GitManagerUI)
|
|
├── git_operations.py (GitOperations)
|
|
├── remote_manager.py (RemoteManager)
|
|
├── utils.py (CommandExecutor, OutputFormatter, InputValidator, PlatformUtils)
|
|
└── config.py (Config)
|
|
```
|
|
|
|
### Key Design Patterns
|
|
|
|
**1. Utility Classes Pattern** (`utils.py`)
|
|
- `CommandExecutor`: Centralized subprocess execution with UTF-8 handling
|
|
- `OutputFormatter`: Consistent colored console output (success/error/info/warning/step)
|
|
- `InputValidator`: User input validation and directory path handling
|
|
- `PlatformUtils`: Cross-platform operations (clear screen, path normalization, platform detection)
|
|
- `Colors`: ANSI color code definitions
|
|
|
|
**2. Operations Layer** (`git_operations.py`)
|
|
- `GitOperations` class manages all Git commands
|
|
- Maintains working directory state (`self.current_dir`)
|
|
- All Git operations use `CommandExecutor` for consistency
|
|
- Methods return `tuple[bool, str]` for success status and output
|
|
|
|
**3. Remote Management** (`remote_manager.py`)
|
|
- Handles GitHub and Gitea remote repository configuration
|
|
- GitHub format: `git@github.com:shumengya/{repo}.git`
|
|
- Gitea format: `ssh://git@git.shumengya.top:8022/{user}/{repo}.git`
|
|
- Manages multiple remotes per repository
|
|
|
|
**4. Configuration** (`config.py`)
|
|
- Centralized configuration in `Config` class
|
|
- Gitea server: `git.shumengya.top:8022`
|
|
- GitHub user: `shumengya`
|
|
- Default branch: `main`
|
|
- Includes comprehensive `.gitignore` template for Node.js, Go, Python projects
|
|
|
|
### Cross-Platform Considerations
|
|
|
|
The codebase handles platform differences through `PlatformUtils`:
|
|
- Path normalization with `os.path.expanduser()` and `os.path.normpath()`
|
|
- Platform detection: `is_windows()`, `is_linux()`, `is_mac()`
|
|
- Clear screen: `cls` (Windows) vs `clear` (Unix)
|
|
- Python command: `python` (Windows) vs `python3` (Unix)
|
|
- UTF-8 encoding explicitly set in subprocess calls
|
|
|
|
### State Management
|
|
|
|
- `GitOperations` maintains `self.current_dir` for the working directory
|
|
- Directory can be changed via `change_directory()` method
|
|
- All Git commands execute in the context of `self.current_dir`
|
|
- UI layer (`ui.py`) orchestrates state between operations and remote management
|
|
|
|
## Important Implementation Details
|
|
|
|
**Commit Message Format:**
|
|
- Default format: `update: YYYY-MM-DD HH:MM:SS` (see `git_operations.py:145`)
|
|
- Generated using `datetime.now().strftime('%Y-%m-%d %H:%M:%S')`
|
|
|
|
**Git Initialization Workflow:**
|
|
1. Run `git init`
|
|
2. Create `main` branch with `git checkout -b main`
|
|
3. Create `.gitignore` from template
|
|
4. Initial commit with message "first commit"
|
|
|
|
**Push Strategy:**
|
|
- First attempts direct push: `git push {remote} {branch}`
|
|
- If fails, retries with upstream: `git push -u {remote} {branch}`
|
|
- This handles first-time pushes to new remotes
|
|
|
|
**Subprocess Execution:**
|
|
- All commands use `shell=True` for compatibility
|
|
- UTF-8 encoding with `errors='ignore'` for robustness
|
|
- Captures both stdout and stderr combined
|
|
- Returns `(success: bool, output: str)` tuple
|
|
|
|
## Configuration Customization
|
|
|
|
To modify default settings, edit `quickgit/config.py`:
|
|
- `GITEA_HOST` and `GITEA_PORT`: Gitea server details
|
|
- `GITHUB_USER`: Default GitHub username
|
|
- `DEFAULT_BRANCH`: Default branch name (currently "main")
|
|
- `GITIGNORE_TEMPLATE`: Template for auto-generated .gitignore files
|
|
|
|
## Testing Considerations
|
|
|
|
When testing or modifying Git operations:
|
|
- Test with both existing and non-existing repositories
|
|
- Verify cross-platform path handling (Windows backslashes vs Unix forward slashes)
|
|
- Test with repositories that have/don't have remotes configured
|
|
- Verify UTF-8 handling for commit messages with non-ASCII characters
|
|
- Test the push retry logic (direct push → upstream push fallback)
|