Skip to content
utkarshgupta188Public

About

GitDude is an AI-powered Git workflow assistant that turns plain English into git actions ,commit, review, recover, and understand your repo from the terminal.

Topics

Resources

Stars

1 star

Watchers

0 watching

Forks

Latest commit

Β 

History

21 Commits

Folders and files

NameName
Last commit message
Last commit date
Β 
Β 
Β 
Β 
Β 
Β 
Β 
Β 
Β 
Β 
Β 
Β 

Repository files navigation

GitDude 🧠

PyPI version Python 3.10+ License: MIT Downloads

GitDude is an AI-powered Git workflow assistant that turns plain English into git actions β€” commit, review, recover, and understand your repo from the terminal.


✨ Features

  • πŸ€– Multi-provider AI β€” Gemini (default, free), Groq (fastest), Ollama (100% local), OpenAI
  • πŸ’¬ Natural language commands β€” gitdude do "stash, switch to main, pull"
  • πŸ” AI code review β€” bugs, security issues, quality flags before you push
  • 🌿 Smart branch naming β€” gitdude branch "fix login problem"
  • πŸ’Ύ Commit only β€” gitdude commit generates messages without pushing
  • πŸ’¬ Codebase chat β€” gitdude chat "how does X work?"
  • πŸš‘ Emergency recovery β€” gitdude whoops diagnoses and fixes git disasters
  • πŸ“‹ PR generation β€” full GitHub PR description, auto-copied to clipboard
  • 🏷️ Automated Tagging β€” gitdude tag suggests versions and generates release notes
  • 🎨 Beautiful Rich UI β€” tables, panels, spinners, color-coded output
  • πŸ” Secure config β€” keys stored in ~/.gitdude/config.json, never in .env

πŸš€ Quick Start

# 1. Install
pip install gitdude

# 2. Configure (takes 60 seconds)
gitdude config

# 3. Generate an AI commit message and push
gitdude push

# 4. Ask about your code
gitdude chat "what does this project do?"

# 5. Review your code before merging
gitdude review

# 6. Something went wrong? Ask for help
gitdude whoops

πŸ“¦ Installation

pip install gitdude

Python 3.10+ required.


πŸ”‘ Provider Setup

Google Gemini (Default β€” Free)

  1. Get an API key from Google AI Studio
  2. Run gitdude config β†’ choose gemini β†’ paste key

Groq (Fastest Free Tier)

  1. Get a key at console.groq.com/keys
  2. Run gitdude config β†’ choose groq β†’ paste key

Ollama (100% Local/Offline)

  1. Install Ollama: ollama.ai
  2. Pull a model: ollama pull llama3
  3. Run gitdude config β†’ choose ollama (no key needed)

OpenAI

  1. Get a key at platform.openai.com
  2. Run gitdude config β†’ choose openai β†’ paste key

πŸ“– Command Reference

gitdude push

AI-generates a commit message for your changes, lets you confirm/edit, then commits and pushes.

gitdude push                            # Stage all β†’ AI commit β†’ push
gitdude push --no-confirm               # Skip confirmation
gitdude push --dry-run                  # Preview only, don't execute
gitdude push --style freeform           # Use freeform (not conventional) commit style
gitdude push --branch feature/auth      # Push to a specific branch
gitdude push --remote upstream          # Push to a specific remote (not just origin)
gitdude push -b new-branch -r origin    # Short flags

Commit types (conventional): feat, fix, chore, docs, refactor, style, test, perf, ci

Push errors: if the push fails, GitDude asks the AI to diagnose the error and suggest fixes. If the fix is judged safe, it offers to run it automatically β€” otherwise you're prompted to Allow / Deny / Allow all remaining for every command before it runs.


gitdude commit

AI-generates a commit message for your changes, lets you confirm/edit, and commits (but does NOT push).

gitdude commit                    # Stage all β†’ AI commit
gitdude commit --no-confirm       # Skip confirmation
gitdude commit --dry-run          # Preview only, don't execute
gitdude commit --style freeform   # Use freeform commit style
gitdude commit --branch feature   # Branch name hint (informational)

gitdude sync

Fetch + rebase. If there are merge conflicts, AI explains what's conflicting and gives exact resolution steps.

gitdude sync
gitdude sync --dry-run

gitdude back

Shows last 30 commits in a table. Pick one to go back to, choose a mode.

gitdude back
gitdude back --dry-run

Modes: soft (keep changes staged), hard (discard changes), checkout (detached HEAD), branch (new branch from that commit)


gitdude do "<natural language>"

Convert plain English into a sequence of git commands, preview, then execute.

gitdude do "stash my changes, switch to main, pull latest"
gitdude do "create a new branch called feature/auth and push it"
gitdude do "squash my last 3 commits" --dry-run

If any command fails, AI reads the error and suggests a fix.

Safety: every generated command is reviewed one-by-one with an Allow / Deny / Allow all remaining prompt before it runs β€” nothing executes without your explicit OK.


gitdude review

Diffs your current branch vs main/master, then AI reviews for bugs, security issues, and quality.

gitdude review
gitdude review --base develop     # Compare against a different branch
gitdude review --dry-run          # Show diff without AI review

Review sections: Summary Β· ⚠️ Potential Bugs Β· πŸ”’ Security Issues Β· πŸ“ Code Quality Β· πŸ” Things to Check Β· βœ… Overall Assessment


gitdude branch "<description>"

AI-generates a clean, conventional branch name from your description.

gitdude branch "fix the login timeout bug"
# β†’ Suggests: fix/login-timeout-bug
# β†’ Prompts: create branch / edit name / cancel

gitdude chat "<question>"

Ask questions about your codebase. It reads your file tree, README, and recent history to provide specific answers.

gitdude chat "how do I add a new command to this app?"
gitdude chat "where is the AI provider logic located?"

gitdude pr

Generates a complete PR title + description + bullet list + testing notes. Auto-copies to clipboard. Falls back to reviewing your local uncommitted changes if there's no branch-vs-base diff.

gitdude pr
gitdude pr --base develop         # Compare against develop
gitdude pr --no-copy              # Don't copy to clipboard

gitdude tag

Scans commits since last tag, suggests next version, and generates release notes. The suggested version is validated against semantic versioning (X.Y.Z) before tagging.

gitdude tag
gitdude tag --no-confirm          # Skip confirmation
gitdude tag --dry-run             # Preview only
gitdude tag --remote upstream     # Push the tag to a specific remote (not just origin)

gitdude whoops

Emergency recovery. Feeds git status + log + reflog to AI. Diagnoses what went wrong and gives step-by-step recovery.

gitdude whoops
gitdude whoops --dry-run          # Diagnose only, don't execute

Safety: dangerous recovery commands are reviewed one-by-one with Allow / Deny / Allow all remaining before executing β€” you're in control of every step.


gitdude config

Interactive configuration wizard.

gitdude config                    # Run setup
gitdude config --show             # Print current config (keys masked)
gitdude config --reset            # Wipe config and redo setup

Stored settings:

  • AI provider (gemini / groq / ollama / openai)
  • API key per provider
  • Model name per provider
  • Default branch (main or master)
  • Commit style (conventional or freeform)

πŸ—οΈ Architecture

gitdude/
β”œβ”€β”€ main.py        # Typer app β€” all command definitions
β”œβ”€β”€ ai.py          # Unified AI provider wrapper (ask_ai)
β”œβ”€β”€ git_ops.py     # GitPython operations (diff, log, push, reset…)
β”œβ”€β”€ config.py      # Config at ~/.gitdude/config.json
└── utils.py       # Rich panels, tables, prompts, helpers

AI Providers (ai.py):

Provider SDK Default Model Speed Cost
gemini google-generativeai gemini-2.0-flash Fast Free tier
groq groq llama-3.3-70b-versatile Fastest Free tier
ollama ollama llama3 Local Free (local)
openai openai gpt-4o-mini Fast Pay per use

All providers go through a single interface: ask_ai(prompt) -> str with spinner feedback and unified error handling.


πŸ›‘οΈ Safety Features

  • βœ… All destructive operations (hard reset, force push, etc.) require explicit confirmation
  • βœ… Per-command Allow/Deny β€” AI-suggested fixes (gitdude do, whoops) and risky push-recovery commands run only after you Allow each one (with an Allow all remaining shortcut)
  • βœ… AI safety classification β€” on push errors the AI first judges whether a fix is safe; safe fixes can be auto-applied (with confirmation), risky ones go through individual review
  • βœ… --dry-run flag available on all mutating commands
  • βœ… Color-coded risk levels β€” green (safe), yellow (caution), red (destructive)
  • βœ… Command-injection safe β€” AI-generated commands run as literal arguments (no shell), so special characters can't execute arbitrary code
  • βœ… No tracebacks β€” all exceptions caught and shown as friendly Rich error panels
  • βœ… API keys stored privately in ~/.gitdude/config.json, never in project files

🀝 Contributing

  1. Fork the repo
  2. Create a feature branch: git checkout -b feat/amazing-feature
  3. Make your changes
  4. Run linting: ruff check .
  5. Open a PR β€” or just use gitdude pr to generate your PR description! πŸ˜„

Dev setup:

git clone https://github.com/utkarshgupta188/gitdude
cd gitdude
pip install -e ".[dev]"

πŸ“„ License

MIT Β© GitDude Contributors

About

GitDude is an AI-powered Git workflow assistant that turns plain English into git actions ,commit, review, recover, and understand your repo from the terminal.

Topics

Resources

Stars

1 star

Watchers

0 watching

Forks

Releases

Contributors

Languages