From 27d231bee506645358c045d4a2edfd1b2db44a68 Mon Sep 17 00:00:00 2001 From: Your Name Date: Sun, 22 Jun 2025 16:57:20 +1200 Subject: [PATCH] docs: Update 2 files --- getpkg/publish.sh | 4 + gp/IMPROVEMENTS.md | 91 -------------- gp/README.md | 304 +++++++++++++++++++++++++++++++++++++++++++++ 3 files changed, 308 insertions(+), 91 deletions(-) delete mode 100644 gp/IMPROVEMENTS.md create mode 100644 gp/README.md diff --git a/getpkg/publish.sh b/getpkg/publish.sh index fba9066..4806b00 100755 --- a/getpkg/publish.sh +++ b/getpkg/publish.sh @@ -45,6 +45,10 @@ docker build \ [ -f "${OUTPUT}/${PROJECT}" ] || die "Build failed." +# compact it! +command -v upx >/dev/null 2>&1 || die "upx not installed" +upx "${OUTPUT}/${PROJECT}" + #-------------------------------------------------------------------------------- SOS="${SCRIPT_DIR}/../sos/sos" [ -f "${SOS}" ] || die "Failed to find sos" diff --git a/gp/IMPROVEMENTS.md b/gp/IMPROVEMENTS.md deleted file mode 100644 index 31d6bae..0000000 --- a/gp/IMPROVEMENTS.md +++ /dev/null @@ -1,91 +0,0 @@ -# GP Script Improvements - -## Original Script Issues - -The original `gp` script had several limitations and potential issues: - -1. **No error handling** - Script could fail silently or in unexpected ways -2. **Unsafe operations** - Always commits and pushes without confirmation -3. **Poor commit messages** - Generated from diff first line, often meaningless -4. **No flexibility** - Hard-coded to push to `main` branch -5. **No dry-run mode** - No way to preview what would happen -6. **Limited functionality** - No help, version, or autocomplete support -7. **Poor user experience** - No colored output or informative messages - -## Improvements Made - -### 1. Safety and Error Handling -- **Strict error handling** with `set -euo pipefail` -- **Git repository validation** before any operations -- **Change detection** to avoid empty commits -- **User confirmation** before committing (unless `--force` used) -- **Proper error messages** with colored output - -### 2. Enhanced Functionality -- **Dry-run mode** (`--dry-run`/`-n`) to preview changes -- **Custom commit messages** - optional argument overrides auto-generation -- **Branch selection** (`--branch`/`-b`) to push to any branch -- **Add-all option** (`--add-all`/`-a`) to include untracked files -- **Force mode** (`--force`/`-f`) to skip confirmations - -### 3. Smart Commit Message Generation -- **File type detection** - recognizes source, config, docs, and test files -- **Change type analysis** - detects additions, modifications, deletions -- **Conventional commit style** - uses prefixes like `feat:`, `docs:`, `test:` -- **Intelligent descriptions** - better context than original script - -### 4. User Experience -- **Colored output** - different colors for info, warnings, errors, success -- **Comprehensive help** - detailed usage information and examples -- **Status display** - shows current branch, repository, and changes -- **Progress feedback** - clear indication of what's happening - -### 5. Integration Features -- **Version command** - reports script version -- **Autocomplete support** - bash completion for options -- **Standard CLI conventions** - follows common command-line patterns - -## Usage Examples - -### Basic Usage -```bash -gp # Auto-generate commit message and push -gp "Fix parser bug" # Use custom commit message -``` - -### Advanced Usage -```bash -gp --dry-run # Preview what would be committed -gp --add-all # Include untracked files -gp --branch develop # Push to develop branch -gp --force "Emergency fix" # Skip confirmation prompt -``` - -### Information Commands -```bash -gp --help # Show help -gp version # Show version -gp autocomplete # Show completion options -``` - -## Benefits - -1. **Safer** - Prevents accidental commits and pushes -2. **More flexible** - Works with different workflows and branching strategies -3. **Better commit history** - Generates meaningful commit messages -4. **User-friendly** - Clear feedback and error messages -5. **Professional** - Follows CLI best practices and conventions -6. **Maintainable** - Well-structured code with proper error handling - -## Backward Compatibility - -The improved script maintains backward compatibility: -- Running `gp` without arguments still auto-generates a commit message and pushes -- The basic workflow is unchanged -- New features are opt-in through command-line flags - -## Installation - -1. Replace the original `gp` script with `gp_improved` -2. Ensure it's executable: `chmod +x gp` -3. The script works from any directory within a git repository \ No newline at end of file diff --git a/gp/README.md b/gp/README.md new file mode 100644 index 0000000..3e810bc --- /dev/null +++ b/gp/README.md @@ -0,0 +1,304 @@ +# GP - Git Push with Smart Commit Messages + +A powerful, safe, and user-friendly Git workflow automation tool that intelligently generates commit messages and streamlines the commit-push process. + +## Features + +### 🚀 **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 +``` + +### Example Workflow +```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 +``` + +## Command Reference + +### Options + +| Option | Description | +|--------|-------------| +| `-h, --help` | Show help message with examples | +| `-n, --dry-run` | Preview changes without executing | +| `-f, --force` | Skip all confirmations | +| `-a, --add-all` | Add all files including untracked (default) | +| `--staged-only` | Only commit staged changes | +| `-b, --branch BRANCH` | Push to specified branch | + +### Commands + +| Command | Description | +|---------|-------------| +| `gp` | Basic usage with smart defaults | +| `gp "message"` | Custom commit message | +| `gp version` | Show version information | +| `gp autocomplete` | Show completion options | + +## 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" +``` + +### Advanced Usage +```bash +# Only commit staged files (don't add untracked) +gp --staged-only + +# Force mode (no confirmations) - good for scripts +gp --force "Automated update" + +# Combine options +gp --dry-run --branch feature/auth "Test authentication changes" +``` + +### 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