diff --git a/README.md b/README.md index 3e810bc..31b1509 100644 --- a/README.md +++ b/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 -# Add all files, generate commit message, and push -gp - -# Use custom commit message -gp "Fix authentication bug in login module" - -# Preview what would happen without executing -gp --dry-run +getpkg install gp ``` -### Example Workflow +## Usage + ```bash -$ gp --dry-run -[INFO] Current branch: main -[INFO] Repository: https://github.com/user/project - -[INFO] Modified files (will be added): - src/auth.py - tests/test_auth.py -[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 +gp # Add all, auto-generate commit message, push +gp "Fix the parser" # Custom commit message +gp --dry-run # Preview without executing +gp --staged-only # Only commit staged changes +gp -y # Skip confirmations +gp -b develop # Push to a specific branch +gp --no-wait # Don't wait for CI after push ``` -## Command Reference - -### Options +## Options | Option | Description | |--------|-------------| -| `-h, --help` | Show help message with examples | | `-n, --dry-run` | Preview changes without executing | | `-f, --force` | Skip all confirmations | +| `-y, --yes` | Auto-answer yes to prompts | | `-a, --add-all` | Add all files including untracked (default) | | `--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 | -|---------|-------------| -| `gp` | Basic usage with smart defaults | -| `gp "message"` | Custom commit message | -| `gp version` | Show version information | -| `gp autocomplete` | Show completion options | +After pushing to a Gitea remote, `gp` automatically monitors the CI workflow progress, showing per-job status: -## Examples - -### Basic Operations -```bash -# Standard workflow - add all files and push -gp - -# Custom commit message -gp "Add user authentication feature" - -# Preview before executing -gp --dry-run - -# Push to different branch -gp --branch develop "Update feature branch" +``` +[INFO] Waiting for CI workflow... (press ESC to stop waiting) + ✓ build (linux/amd64) + ⠹ build (linux/arm64) running + · test-install (linux/amd64) queued + · test-install (linux/arm64) queued ``` -### Advanced Usage -```bash -# Only commit staged files (don't add untracked) -gp --staged-only +- Press **ESC** at any time to stop waiting (CI continues in background) +- Requires a Gitea API token (extracted from the remote URL or `GITEA_TOKEN` env var) +- Automatically skipped for GitHub/GitLab remotes or when no token is available +- Use `--no-wait` to disable -# Force mode (no confirmations) - good for scripts -gp --force "Automated update" +## Commit Message Generation -# Combine options -gp --dry-run --branch feature/auth "Test authentication changes" -``` +Uses Claude AI (`claude --print`) if available, otherwise falls back to heuristic analysis: -### Handling Different Scenarios - -#### When you have unpushed commits: -```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.** \ No newline at end of file +- 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` +- File type prefixes: `feat:`, `docs:`, `test:`, `config:`