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:

   curl -o gp https://raw.githubusercontent.com/your-repo/gp/main/gp
   chmod +x gp
   

2. Place in your PATH:

   mv gp ~/.local/bin/
   # or
   sudo mv gp /usr/local/bin/
   

3. Verify installation:

   gp version
   

Quick Start

Basic Usage

# 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

$ 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

# 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

# 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:

$ 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:

$ 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

$ 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:

# 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:

[alias]
    p = !gp
    pd = !gp --dry-run
    pf = !gp --force

CI/CD Integration

# 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:

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

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