An intelligent Git CLI that automates staging, Conventional Commit messages (via Gemini), branch flow, and push/merge in one go.
npm install @gunjanghate/git-geniegg with no arguments opens a menu to pick actions; it shows the exact command it will run.
gg b, gg s, gg wt, gg cl for fast branch/worktree/clone flows.
--type, the CLI infers a sensible commit type from the diff.
--no-branch skips the branch prompt and commits directly to main.
--push-to-main pushes automatically. If you’re on a feature branch, it merges into main and pushes; if you’re on main, it just pushes.
bash
npm install -g @gunjanghate/git-genie
`
$3
Before using AI features, configure your Gemini API key:
`bash
gg config YOUR_GEMINI_API_KEY
`
$3
`bash
Manual commit message (default)
gg "add new feature"
AI-generated commit message
gg "fix authentication bug" --genie
Commit directly to main (skip branch prompt)
gg "update documentation" --no-branch
Merge to main and push after commit
gg "add dashboard" --type feat --push-to-main
`
Configuration Management
$3
GitGenie supports multiple ways to configure your Gemini API key:
#### Method 1: Using the config command (Recommended)
`bash
gg config YOUR_GEMINI_API_KEY
`
This saves the API key to ~/.gitgenie/config.json for persistent use across all projects.
#### Method 2: Environment variable
`bash
export GEMINI_API_KEY="your_api_key_here"
`
#### Method 3: .env file in project directory
Create a .env file in your project root:
`properties
GEMINI_API_KEY=your_api_key_here
`
Priority Order: Environment variable > Config file > .env file
$3
1. Visit Google AI Studio
2. Create a new API key
3. Configure it using one of the methods above
Key Features
- Validates Git repository existence and initializes if needed
- Automatic file staging with progress feedback
- AI-powered commit message generation using Google Gemini
- Open source contribution workflow with --osc flag (issue-based branch naming)
- Interactive branch management with auto-suggestions
- Automated merge-to-main workflows
- Retry logic for network operations
- Professional error handling and user feedback
- Cross-platform configuration management
CLI Commands and Options
$3
GitGenie includes convenient shortcut commands for branch, remote, and worktree operations:
- gg b : Create and switch to a new branch
- gg s : Switch to an existing branch
- gg wt : Create a worktree for a branch at an optional path
- gg cl : Clone a repository into an optional directory
- gg setup : Configure upstream, sync main from it, and create/switch to a feature branch
- gg us add : Add an upstream remote pointing to the original repo
- gg us sync: Sync your local main from upstream/main and optionally push to origin/main
- gg wt ls: List all existing worktrees with branches and paths
- gg wt rm : Remove the worktree associated with the given branch
- gg goto : Show (and try to open) the worktree folder for a branch
#### Examples:
`bash
Create and switch to a new branch
gg b feature/new-ui
Switch to an existing branch
gg s main
Create a worktree for a branch (default path is a folder named after the branch)
gg wt pr2
Create a worktree for a branch at a custom path
gg wt pr2 ../pr2-folder
Clone a repository
gg cl https://github.com/username/repo.git
Clone a repository to a specific directory
gg cl https://github.com/username/repo.git my-custom-folder
One-shot fork setup: configure upstream, sync main, and create a feature branch
gg setup https://github.com/original/repo.git fix/navbar-bug
Equivalent internal steps:
git remote add upstream https://github.com/original/repo.git
git checkout main
git pull upstream main
git push origin main # if origin exists
git checkout -b fix/navbar-bug
Add an upstream remote (original repo)
gg us add https://github.com/original/repo.git
Sync local main from upstream and push to origin
gg us sync
List and remove worktrees
gg wt ls
gg wt rm docs/readme-update
Show path for worktree and open in VS Code
gg goto docs/readme-update
`
$3
- Run gg with no arguments to open an interactive menu.
- Pick actions like “commit”, “b”, “s”, “wt”, or “cl”.
- The palette prints the exact command it will run and then executes it.
Example
`
gg
→ Running: gg "add login retries" --type fix --scope auth
`
These shortcuts make branch and worktree management faster and easier, especially for advanced workflows and multi-branch development.
$3
`bash
gg [options]
`
$3
`bash
gg config # Save Gemini API key for persistent use
`
$3
- : Short description of the change (mandatory)
- --type : Commit type (if omitted and not using --genie, GitGenie will auto-detect a likely type from your changes)
- --scope : Optional scope for commit message
- --genie: Enable AI commit message generation using Google Gemini
- Auto-detect commit type (non-genie): If you don’t pass --type and you’re not using --genie, GitGenie will infer a likely type from your changes.
- --osc: Open source contribution branch format (prompts for issue number, branch name: type/#issue-shorttitle)
- --no-branch: Skip interactive branch choice and commit to main
- --push-to-main: Automatically merge current branch to main and push
- --remote : Add remote origin if repo is new
$3
- feat: New features
- fix: Bug fixes
- docs: Documentation changes
- style: Code style changes
- refactor: Code refactoring
- test: Adding or updating tests
- chore: Maintenance tasks
- ci: CI/CD changes
- build: Build system changes
- perf: Performance improvements
Project Structure
`
GitGenie Project/
├── ~/.gitgenie/
│ └── config.json # User configuration file
├── .env # Optional project environment variables
├── .git/ # Git repository data
├── .gitignore # Git ignore rules
├── index.js # Main application logic
├── node_modules/ # Dependencies
├── package.json # Project configuration & dependencies
├── package-lock.json # Locked dependency versions
└── README.md # This documentation
`
Core Features
$3
- Automatic repository detection and initialization
- Smart remote origin setup
- Default branch configuration to main
- Comprehensive repository state validation
$3
- Interactive branch selection with current branch display
- Auto-suggested branch names using format: type/description-YYYY-MM-DD
- Support for direct main branch commits with --no-branch
- Safe branch creation and switching
$3
- Detects unstaged changes automatically
- Stages all files when no staged changes found
- Progress feedback during staging operations
- Robust error handling for staging failures
$3
- Manual mode (default): Uses conventional commit format type(scope): description
- AI mode (--genie): Powered by Google Gemini 2.0 Flash model
- Professional Conventional Commits specification compliance
- Intelligent analysis of code diffs for contextual commit messages
- Graceful fallback to manual mode when AI fails
- Support for all conventional commit types and scopes
#### Auto-detect commit type (non-genie)
- When you don’t pass --type and you’re not using --genie, GitGenie analyzes your staged changes and picks a suitable commit type (e.g., fix, docs, refactor).
- You’ll see a log like:
`
🧠 Auto-detected commit type: fix
`
- Override any time by passing --type explicitly.
$3
- Interactive push confirmation with retry logic
- Automated merge-to-main functionality with --push-to-main
- Feature branch cleanup after successful merges
- Remote branch synchronization and management
- Network failure resilience with automatic retries
$3
- Clean, corporate-friendly messaging
- Real-time progress indicators with spinners
- Colored output for better readability
- Comprehensive error handling with helpful messages
- Cross-platform compatibility
Dependencies & Technology Stack
$3
- @google/generative-ai (latest): Google Gemini AI integration
- commander (v14.0.0): CLI argument parsing and command structure
- simple-git (v3.28.0): Git operations and repository management
- inquirer (v12.9.2): Interactive command line prompts
- chalk (v5.5.0): Terminal color and styling
- ora (v8.2.0): Progress spinners and status indicators
- dotenv (v17.2.1): Environment variable management
$3
- Package: gitgenie-cli
- Version: 1.0.0+
- Module Type: ES6 modules
- Global Command: gg
- Entry Point: index.js
- Node Version: 16+ recommended
$3
Open source contribution branch (manual short title)
gg "fix login bug" --osc
Open source contribution branch (AI short title)
gg "fix login bug" --osc --genie
#### Basic Usage:
`powershell
Navigate to project directory
cd "d:\my\GUNJAN\Git Butler"
Install dependencies (if needed)
npm install
Basic commit with manual message (default behavior)
gg "add new feature"
Commit with AI-generated message using Gemini
gg "fix authentication bug" --genie
Commit with specific type and scope
gg "fix authentication bug" --type fix --scope auth
Commit with AI, specific type and scope
gg "optimize database queries" --type perf --scope db --genie
Commit directly to main branch (no AI)
gg "update documentation" --no-branch
Automatically merge to main and push
gg "add user dashboard" --type feat --push-to-main
Initialize new repo with remote
gg "initial commit" --remote https://github.com/username/repo.git --no-branch
`
#### Interactive Workflow Example:
`powershell
Run with interactive prompts
gg "implement user management"
The tool will ask:
1. Current branch is "main". Where do you want to commit?
- Commit to current branch (main)
- Create a new branch
#
2. If creating new branch:
Enter new branch name: feat/implement-user-management-2025-09-01
#
3. After commit:
Do you want to push branch "feat/implement-user-management-2025-09-01" to remote? (Y/n)
`
#### Advanced Usage Scenarios:
`powershell
Testing the CLI tool functionality with AI
gg "test file modifications" --type test --scope cli --genie
Bug fix with specific scope (manual commit)
gg "resolve merge conflicts" --type fix --scope git
Feature addition with AI-generated commit message
gg "add interactive branch selection" --type feat --scope branch --genie
Documentation update directly to main
gg "update README with examples" --type docs --no-branch
Performance improvement with AI and auto-merge to main
gg "optimize database queries" --type perf --scope db --genie --push-to-main
`
#### Legacy Examples:
`bash
First commit to a new repo, main branch, manual commit
gg "initial commit" --no-branch --remote https://github.com/username/git-genie.git
Commit to existing repo, interactive branch selection & AI commit
gg "add interactive branch selection" --type feat --scope commit --genie
Commit to current branch directly with manual message
gg "fix typo in README" --no-branch
`
$3
1. CLI parses user input and options.
2. Initializes Git repository if none exists.
3. Adds remote origin if provided.
4. Checks for existing commits.
5. Prompts the user to choose the branch (interactive) or commits directly to main if --no-branch.
- If --osc is used and new branch is selected, prompts for issue number and generates branch name as type/#issue-shorttitle (shorttitle by Gemini if --genie, otherwise from message)
6. Stages all files if needed.
7. Generates commit message (AI with --genie flag or manual by default).
8. Commits the changes.
9. Handles push logic based on --push-to-main flag or interactive prompts.
10. Optionally merges to main branch and pushes with retry logic.
11. Provides detailed console feedback for every step.
---
🛠 How Git genie Works (Detailed Step-by-Step)
1. Repository Check: Verifies if current directory is a Git repo, initializes if not
2. Remote Setup: Adds remote origin if provided via --remote flag
3. Commit History Check: Determines if repository has existing commits
4. Branch Decision:
- If --no-branch or no commits: commits to main
- Otherwise: interactive prompt to choose current branch or create new one
5. File Staging: Checks for staged changes, auto-stages all files if none found
6. Commit Message Generation:
- Uses Gemini AI to analyze diff and generate commit message
- Falls back to manual format if AI disabled or fails
7. Commit Execution: Commits staged files with generated message
8. Push Confirmation: Asks user if they want to push to remote
9. Push with Retry: Attempts to push with retry logic for network failures
🎯 Key Features & Benefits
✅ Automated Git Workflows - Reduces manual Git command typing
✅ AI-Generated Commit Messages - Professional, contextual commit messages
✅ Open Source Contribution Helper - Issue-based branch naming for open source PRs
✅ Interactive Branch Management - User-friendly branch creation and switching
✅ Smart Error Handling - Graceful fallbacks and retry mechanisms
✅ Professional Formatting - Conventional Commit standards
✅ Colored Output - Clear visual feedback with chalk
✅ Spinner Feedback - Real-time progress indicators
✅ Flexible Configuration - Multiple CLI options for different workflows
🧪 Testing Commands
`powershell
Test basic functionality
gg "test basic functionality" --no-ai --no-branch
Test AI commit generation
gg "test AI commit generation" --type test
Test branch creation
gg "test branch creation" --type feat --scope testing
Test error handling (no changes)
gg "test no changes scenario" --no-branch
Test with different commit types
gg "test documentation" --type docs
gg "test bug fix" --type fix
gg "test refactoring" --type refactor
`
📋 Notes
- If no remote is configured, the CLI offers to add one before pushing. You can skip this and push later.
- Unknown commands provide helpful suggestions.
---
Notes & Future Considerations
- Add interactive guided mode for beginners (e.g., --wizard)
- Add command autocomplete and suggestions
- Add onboarding welcome for first-time users
- Add undo/redo for git actions
- Add more help and examples in CLI output
- Can implement last-used branch suggestion for faster workflow.
- Optional integration with other AI models for commit suggestions.
- Ability to include commit templates for faster conventional commit adherence.
- Extend CLI with commands like git-genie status, git-genie log`, etc.