GitGuru

Best Practices

Tips and recommendations for getting the most out of GitGuru.

Safety First

GitGuru includes several safety features. Make sure to use them:

Use Dry-Run Mode

Before executing potentially destructive operations, preview what will happen:

bash
# Preview push
gg push --dry-run

# Preview sync
gg sync --dry-run

# Preview what would be pulled
gg pull --dry-run
Make It a Habit
Always use --dry-run for operations you're unsure about. It's better to preview than to regret!

Understand Safety Levels

When using gg ask, pay attention to the safety indicators:

  • 🟢 Safe - Go ahead without worry. These are read-only operations.
  • 🟡 Caution - Double-check before executing. Changes are usually reversible.
  • 🔴 Dangerous - Be very careful! These can permanently delete data or rewrite history.

Don't Skip Confirmations

While -y flag skips confirmations, use it sparingly:

bash
# Safe for read-only operations
gg ask "show last commit" -y

# DON'T skip confirmation for destructive operations
gg ask "delete all untracked files"  # Read the warning first!

Writing Good Commits

AI-Assisted Commit Workflow

For the best AI-generated commit messages:

  1. Stage related changes together - Don't mix unrelated changes in one commit
  2. Review staged changes first - Use gg diff --staged
  3. Generate AI message - Use gg commit --ai
  4. Review and modify if needed - The AI suggestion is a starting point
bash
# Good workflow
gg add src/auth/              # Stage related files
gg diff --staged --ai         # Review changes with AI summary
gg commit --ai                # Generate commit message

Conventional Commit Format

GitGuru generates commits in the conventional format. Learn the types:

TypeWhen to Use
feat:New feature or functionality
fix:Bug fix
docs:Documentation changes
style:Code formatting, no logic change
refactor:Code restructuring without behavior change
test:Adding or updating tests
chore:Maintenance tasks, dependencies

Asking Effective Questions

Be Specific

The more specific your question, the better the AI response:

bash
# Vague - might get generic response
gg ask "undo changes"

# Specific - gets precise command
gg ask "undo last commit but keep my changes staged"

# Very specific - best results
gg ask "undo last 3 commits and squash them into one"

Describe Your Intent

Tell GitGuru what you're trying to achieve, not just what command you need:

bash
# Good: describes intent
gg ask "I accidentally committed to main, how do I move it to a feature branch?"

# Good: provides context
gg ask "I need to find which commit introduced a bug in the login function"

# Good: explains desired outcome
gg ask "clean up my local branches that have already been merged to main"

Learning Git with GitGuru

Use Explain Before Ask

If you're learning Git, understand concepts before executing commands:

bash
# First, understand the concept
gg explain rebase

# Then, when you understand it, get help with specific task
gg ask "rebase my feature branch onto main"

Read the AI Explanations

Don't just execute commands blindly. Read what they do:

  • Read the "What this does" section
  • Note any warnings
  • Consider the alternatives suggested
  • Understand why a command might be dangerous

Working with Teams

Consistent Commit Messages

Using AI-generated commits helps maintain consistency across your team:

bash
# Everyone uses the same format
gg commit --ai

# Results in consistent history:
# feat: add user authentication with OAuth2
# fix: resolve race condition in data fetching
# docs: update API reference for v2 endpoints

Review Before Pushing

Always review what you're about to push:

bash
# Check what will be pushed
gg push --dry-run

# Review commit history
gg log -n 5

# Then push
gg push

Performance Tips

Choose the Right Model

Use faster models for quick tasks:

bash
# For quick, everyday tasks
gg config --set ai.model=gemini-1.5-flash

# For complex analysis (when needed)
gg config --set ai.model=gemini-1.5-pro

Use AI Selectively

Don't enable all AI features by default. Use them when needed:

bash
# Keep defaults minimal
gg config --set ai.commit.enabled=true   # Most useful
gg config --set ai.diff.enabled=false    # Use --ai when needed
gg config --set ai.status.enabled=false  # Use --ai when needed
gg config --set ai.log.enabled=false     # Use --ai when needed

# Then use --ai flag when you want AI analysis
gg diff --ai
gg status --ai

Troubleshooting Tips

If AI Isn't Responding Well

  • Try rephrasing your question
  • Be more specific about what you want
  • Check your API key is valid
  • Try a different model

GitGuru Fails Gracefully

If AI features fail, GitGuru falls back to manual mode. You can always use:

bash
# Manual commit message
gg commit "feat: add new feature"

# Regular Git commands still work
git status
git log

Summary

Key Takeaways
  • ✓ Always use --dry-run for unfamiliar operations
  • ✓ Pay attention to safety levels in AI suggestions
  • ✓ Stage related changes together for better commit messages
  • ✓ Be specific when asking questions
  • ✓ Use gg explain to learn Git concepts
  • ✓ Review before pushing
  • ✓ Choose the right AI model for your needs

Next Steps