getpkg/gp/README.md

# 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.**