Update README.md
This commit is contained in:
j
314
README.md
314
README.md
@@ -1,304 +1,58 @@
|
|||||||
# GP - Git Push with Smart Commit Messages
|
# gp - Git Push
|
||||||
|
|
||||||
A powerful, safe, and user-friendly Git workflow automation tool that intelligently generates commit messages and streamlines the commit-push process.
|
Add, commit, and push in one command. Generates commit messages using Claude AI with a heuristic fallback.
|
||||||
|
|
||||||
## Features
|
## Install
|
||||||
|
|
||||||
### 🚀 **Smart Commit Messages**
|
|
||||||
- **File type detection** - Recognizes source code, config files, documentation, and tests
|
|
||||||
- **Change analysis** - Detects additions, modifications, deletions, and renames
|
|
||||||
- **Conventional commits** - Uses prefixes like `feat:`, `docs:`, `test:`, `config:`
|
|
||||||
- **Intelligent descriptions** - Context-aware commit messages based on actual changes
|
|
||||||
|
|
||||||
### 🛡️ **Safety First**
|
|
||||||
- **Preview mode** - `--dry-run` shows exactly what will happen before executing
|
|
||||||
- **User confirmation** - Always asks before adding files or pushing changes
|
|
||||||
- **Change detection** - Prevents empty commits and handles unpushed commits
|
|
||||||
- **Clear feedback** - Colored output with detailed status information
|
|
||||||
|
|
||||||
### ⚡ **Workflow Enhancement**
|
|
||||||
- **Add-all default** - Automatically includes untracked and modified files
|
|
||||||
- **Unpushed commit handling** - Detects and offers to push existing commits
|
|
||||||
- **Branch flexibility** - Push to any branch with `--branch` option
|
|
||||||
- **Force mode** - Skip confirmations for automation scripts
|
|
||||||
|
|
||||||
### 🎯 **Professional CLI**
|
|
||||||
- **Comprehensive help** - Built-in documentation with examples
|
|
||||||
- **Bash completion** - Tab completion for all options
|
|
||||||
- **Version tracking** - Semantic versioning support
|
|
||||||
- **Standard conventions** - Follows Unix CLI best practices
|
|
||||||
|
|
||||||
## Installation
|
|
||||||
|
|
||||||
1. **Download the script:**
|
|
||||||
```bash
|
|
||||||
curl -o gp https://raw.githubusercontent.com/your-repo/gp/main/gp
|
|
||||||
chmod +x gp
|
|
||||||
```
|
|
||||||
|
|
||||||
2. **Place in your PATH:**
|
|
||||||
```bash
|
|
||||||
mv gp ~/.local/bin/
|
|
||||||
# or
|
|
||||||
sudo mv gp /usr/local/bin/
|
|
||||||
```
|
|
||||||
|
|
||||||
3. **Verify installation:**
|
|
||||||
```bash
|
|
||||||
gp version
|
|
||||||
```
|
|
||||||
|
|
||||||
## Quick Start
|
|
||||||
|
|
||||||
### Basic Usage
|
|
||||||
```bash
|
```bash
|
||||||
# Add all files, generate commit message, and push
|
getpkg install gp
|
||||||
gp
|
|
||||||
|
|
||||||
# Use custom commit message
|
|
||||||
gp "Fix authentication bug in login module"
|
|
||||||
|
|
||||||
# Preview what would happen without executing
|
|
||||||
gp --dry-run
|
|
||||||
```
|
```
|
||||||
|
|
||||||
### Example Workflow
|
## Usage
|
||||||
|
|
||||||
```bash
|
```bash
|
||||||
$ gp --dry-run
|
gp # Add all, auto-generate commit message, push
|
||||||
[INFO] Current branch: main
|
gp "Fix the parser" # Custom commit message
|
||||||
[INFO] Repository: https://github.com/user/project
|
gp --dry-run # Preview without executing
|
||||||
|
gp --staged-only # Only commit staged changes
|
||||||
[INFO] Modified files (will be added):
|
gp -y # Skip confirmations
|
||||||
src/auth.py
|
gp -b develop # Push to a specific branch
|
||||||
tests/test_auth.py
|
gp --no-wait # Don't wait for CI after push
|
||||||
[INFO] Untracked files (will be added):
|
|
||||||
docs/auth.md
|
|
||||||
|
|
||||||
[WARNING] Files will be automatically added before committing
|
|
||||||
[INFO] Generated commit message: 'feat: Update 3 files'
|
|
||||||
[WARNING] DRY RUN MODE - No changes will be made
|
|
||||||
[INFO] Would commit with message: 'feat: Update 3 files'
|
|
||||||
[INFO] Would push to: origin/main
|
|
||||||
```
|
```
|
||||||
|
|
||||||
## Command Reference
|
## Options
|
||||||
|
|
||||||
### Options
|
|
||||||
|
|
||||||
| Option | Description |
|
| Option | Description |
|
||||||
|--------|-------------|
|
|--------|-------------|
|
||||||
| `-h, --help` | Show help message with examples |
|
|
||||||
| `-n, --dry-run` | Preview changes without executing |
|
| `-n, --dry-run` | Preview changes without executing |
|
||||||
| `-f, --force` | Skip all confirmations |
|
| `-f, --force` | Skip all confirmations |
|
||||||
|
| `-y, --yes` | Auto-answer yes to prompts |
|
||||||
| `-a, --add-all` | Add all files including untracked (default) |
|
| `-a, --add-all` | Add all files including untracked (default) |
|
||||||
| `--staged-only` | Only commit staged changes |
|
| `--staged-only` | Only commit staged changes |
|
||||||
| `-b, --branch BRANCH` | Push to specified branch |
|
| `-b, --branch` | Push to specified branch |
|
||||||
|
| `--no-wait` | Skip waiting for CI workflow |
|
||||||
|
|
||||||
### Commands
|
## CI Workflow Monitoring
|
||||||
|
|
||||||
| Command | Description |
|
After pushing to a Gitea remote, `gp` automatically monitors the CI workflow progress, showing per-job status:
|
||||||
|---------|-------------|
|
|
||||||
| `gp` | Basic usage with smart defaults |
|
|
||||||
| `gp "message"` | Custom commit message |
|
|
||||||
| `gp version` | Show version information |
|
|
||||||
| `gp autocomplete` | Show completion options |
|
|
||||||
|
|
||||||
## Examples
|
```
|
||||||
|
[INFO] Waiting for CI workflow... (press ESC to stop waiting)
|
||||||
### Basic Operations
|
✓ build (linux/amd64)
|
||||||
```bash
|
⠹ build (linux/arm64) running
|
||||||
# Standard workflow - add all files and push
|
· test-install (linux/amd64) queued
|
||||||
gp
|
· test-install (linux/arm64) queued
|
||||||
|
|
||||||
# Custom commit message
|
|
||||||
gp "Add user authentication feature"
|
|
||||||
|
|
||||||
# Preview before executing
|
|
||||||
gp --dry-run
|
|
||||||
|
|
||||||
# Push to different branch
|
|
||||||
gp --branch develop "Update feature branch"
|
|
||||||
```
|
```
|
||||||
|
|
||||||
### Advanced Usage
|
- Press **ESC** at any time to stop waiting (CI continues in background)
|
||||||
```bash
|
- Requires a Gitea API token (extracted from the remote URL or `GITEA_TOKEN` env var)
|
||||||
# Only commit staged files (don't add untracked)
|
- Automatically skipped for GitHub/GitLab remotes or when no token is available
|
||||||
gp --staged-only
|
- Use `--no-wait` to disable
|
||||||
|
|
||||||
# Force mode (no confirmations) - good for scripts
|
## Commit Message Generation
|
||||||
gp --force "Automated update"
|
|
||||||
|
|
||||||
# Combine options
|
Uses Claude AI (`claude --print`) if available, otherwise falls back to heuristic analysis:
|
||||||
gp --dry-run --branch feature/auth "Test authentication changes"
|
|
||||||
```
|
|
||||||
|
|
||||||
### Handling Different Scenarios
|
- Single file: `Add src/auth.py`, `Update README.md`, `Remove old_config.json`
|
||||||
|
- Multiple files: `feat: Add 2 and update 3 files`, `docs: Update 2 files`
|
||||||
#### When you have unpushed commits:
|
- File type prefixes: `feat:`, `docs:`, `test:`, `config:`
|
||||||
```bash
|
|
||||||
$ gp
|
|
||||||
[INFO] No staged changes, but found 2 unpushed commit(s)
|
|
||||||
[INFO] Latest unpushed commit: abc1234 Fix parser bug
|
|
||||||
|
|
||||||
Push existing commits to origin/main? [y/N] y
|
|
||||||
[SUCCESS] Successfully pushed existing commits to origin/main
|
|
||||||
```
|
|
||||||
|
|
||||||
#### When you have mixed changes:
|
|
||||||
```bash
|
|
||||||
$ gp --staged-only
|
|
||||||
[INFO] Staged changes:
|
|
||||||
src/main.py
|
|
||||||
[INFO] Modified files (unstaged, will NOT be included):
|
|
||||||
README.md
|
|
||||||
[WARNING] Unstaged changes will NOT be included (use -a to include them)
|
|
||||||
```
|
|
||||||
|
|
||||||
## Smart Commit Message Examples
|
|
||||||
|
|
||||||
GP analyzes your changes and generates meaningful commit messages:
|
|
||||||
|
|
||||||
### Single File Changes
|
|
||||||
- `Add src/auth.py` - New file added
|
|
||||||
- `Update README.md` - Existing file modified
|
|
||||||
- `Remove old_config.json` - File deleted
|
|
||||||
|
|
||||||
### Multiple Files by Type
|
|
||||||
- `feat: Update 3 files` - Source code changes
|
|
||||||
- `docs: Update 2 files` - Documentation changes
|
|
||||||
- `test: Update 4 files` - Test file changes
|
|
||||||
- `config: Update 2 files` - Configuration changes
|
|
||||||
|
|
||||||
### File Type Detection
|
|
||||||
- **Source files**: `.py`, `.js`, `.cpp`, `.go`, `.rs`, etc.
|
|
||||||
- **Config files**: `.json`, `.yml`, `.toml`, `CMakeLists.txt`, etc.
|
|
||||||
- **Documentation**: `.md`, `.txt`, `.rst`, `README*`, `docs/*`
|
|
||||||
- **Tests**: `*test*`, `*spec*`, `test/*`, `tests/*`
|
|
||||||
|
|
||||||
## Safety Features
|
|
||||||
|
|
||||||
### Confirmation Prompts
|
|
||||||
```bash
|
|
||||||
$ gp
|
|
||||||
[INFO] Untracked files (will be added):
|
|
||||||
new_feature.py
|
|
||||||
tests/test_new_feature.py
|
|
||||||
|
|
||||||
Add these files and continue? [y/N] _
|
|
||||||
```
|
|
||||||
|
|
||||||
### Change Detection
|
|
||||||
- ✅ **Prevents empty commits** - Exits gracefully when no changes
|
|
||||||
- ✅ **Handles unpushed commits** - Offers to push existing commits
|
|
||||||
- ✅ **Validates git repository** - Ensures you're in a valid repo
|
|
||||||
- ✅ **Branch validation** - Confirms target branch exists
|
|
||||||
|
|
||||||
### Error Handling
|
|
||||||
- Clear error messages with suggested solutions
|
|
||||||
- Graceful handling of network issues
|
|
||||||
- Proper exit codes for script integration
|
|
||||||
|
|
||||||
## Configuration
|
|
||||||
|
|
||||||
### Environment Variables
|
|
||||||
None required - GP works out of the box.
|
|
||||||
|
|
||||||
### Git Configuration
|
|
||||||
GP respects your existing Git configuration:
|
|
||||||
- Uses your configured remote origin
|
|
||||||
- Respects Git ignore files
|
|
||||||
- Works with your existing Git hooks
|
|
||||||
|
|
||||||
## Integration
|
|
||||||
|
|
||||||
### Bash Completion
|
|
||||||
Add to your `.bashrc`:
|
|
||||||
```bash
|
|
||||||
# GP completion
|
|
||||||
_gp_completion() {
|
|
||||||
local cur="${COMP_WORDS[COMP_CWORD]}"
|
|
||||||
local opts=$(gp autocomplete)
|
|
||||||
COMPREPLY=($(compgen -W "$opts" -- "$cur"))
|
|
||||||
}
|
|
||||||
complete -F _gp_completion gp
|
|
||||||
```
|
|
||||||
|
|
||||||
### Git Aliases
|
|
||||||
Add to your `.gitconfig`:
|
|
||||||
```ini
|
|
||||||
[alias]
|
|
||||||
p = !gp
|
|
||||||
pd = !gp --dry-run
|
|
||||||
pf = !gp --force
|
|
||||||
```
|
|
||||||
|
|
||||||
### CI/CD Integration
|
|
||||||
```bash
|
|
||||||
# In your CI script
|
|
||||||
gp --force "Automated deployment [skip ci]"
|
|
||||||
```
|
|
||||||
|
|
||||||
## Troubleshooting
|
|
||||||
|
|
||||||
### Common Issues
|
|
||||||
|
|
||||||
#### "Not in a git repository"
|
|
||||||
- **Solution**: Run GP from within a Git repository
|
|
||||||
- **Check**: `git status` should work
|
|
||||||
|
|
||||||
#### "No changes to commit"
|
|
||||||
- **Cause**: Working tree is clean
|
|
||||||
- **Check**: `git status` to see if there are any changes
|
|
||||||
|
|
||||||
#### "Failed to push"
|
|
||||||
- **Cause**: Usually needs to pull first
|
|
||||||
- **Solution**: `git pull origin main` then try again
|
|
||||||
|
|
||||||
#### VSCode showing shellcheck errors
|
|
||||||
- **Solution**: Restart VSCode or reload the shellcheck extension
|
|
||||||
- **Check**: Command line `shellcheck gp` should show no errors
|
|
||||||
|
|
||||||
### Debug Mode
|
|
||||||
For verbose output, modify the script to set:
|
|
||||||
```bash
|
|
||||||
set -x # Add after the shebang line for debug output
|
|
||||||
```
|
|
||||||
|
|
||||||
## Contributing
|
|
||||||
|
|
||||||
### Development
|
|
||||||
1. Fork the repository
|
|
||||||
2. Make your changes
|
|
||||||
3. Test with `shellcheck gp`
|
|
||||||
4. Submit a pull request
|
|
||||||
|
|
||||||
### Testing
|
|
||||||
```bash
|
|
||||||
# Lint the script
|
|
||||||
shellcheck gp
|
|
||||||
|
|
||||||
# Test basic functionality
|
|
||||||
./gp --dry-run
|
|
||||||
|
|
||||||
# Test with various scenarios
|
|
||||||
echo "test" > test.txt && ./gp --dry-run
|
|
||||||
```
|
|
||||||
|
|
||||||
## License
|
|
||||||
|
|
||||||
MIT License - see LICENSE file for details.
|
|
||||||
|
|
||||||
## Version History
|
|
||||||
|
|
||||||
- **v2.0.0** - Complete rewrite with safety features and smart commit messages
|
|
||||||
- **v1.0.0** - Basic git automation script
|
|
||||||
|
|
||||||
## Support
|
|
||||||
|
|
||||||
- **Issues**: Report bugs and feature requests on GitHub
|
|
||||||
- **Documentation**: This README and built-in help (`gp --help`)
|
|
||||||
- **Examples**: See the examples section above
|
|
||||||
|
|
||||||
---
|
|
||||||
|
|
||||||
**Made with ❤️ for developers who value safety and efficiency in their Git workflow.**
|
|
||||||
|
|||||||
Reference in New Issue
Block a user