GitGenie CLI - Complete Documentation

Overview

GitGenie is an intelligent command-line interface (CLI) tool designed to simplify and automate Git workflows. It handles common Git operations like committing, branch management, staging, and pushing, while optionally integrating AI-generated commit messages using Google Gemini. This comprehensive documentation details all features, configurations, and functionality implemented to date.

What's New

• Interactive Command Palette: running gg with no arguments opens a menu to pick actions; it shows the exact command it will run.
• Shortcuts: gg b, gg s, gg wt, gg cl for fast branch/worktree/clone flows.
• Auto-Detect Commit Type: in non-genie mode, if you don’t pass --type, the CLI infers a sensible commit type from the diff.
• Non-interactive flags:
  • --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.

Quick Start

Installation

npm install -g @gunjanghate/git-genie

Configuration

Before using AI features, configure your Gemini API key:

gg config YOUR_GEMINI_API_KEY

Basic Usage

# 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

Setting up Gemini API Key

GitGenie supports multiple ways to configure your Gemini API key:

Method 1: Using the config command (Recommended)

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

export GEMINI_API_KEY="your_api_key_here"

Method 3: .env file in project directory

Create a .env file in your project root:

GEMINI_API_KEY=your_api_key_here

Priority Order: Environment variable > Config file > .env file

Getting a Gemini API Key

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

Branch Management Shortcuts

GitGenie now includes convenient shortcut commands for branch management and worktree operations:

• gg b <branchName>: Create and switch to a new branch
• gg s <branchName>: Switch to an existing branch
• gg wt <branchName> [path]: Create a worktree for a branch at an optional path
• gg cl <repoUrl> [directory]: Clone a repository into an optional directory

Examples:

# 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

Command Palette (no-args menu)

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

Main Command

gg <description> [options]

Configuration Command

gg config <api-key>    # Save Gemini API key for persistent use

Available Options

• <desc>: Short description of the change (mandatory)
• --type <type>: Commit type (if omitted and not using --genie, GitGenie will auto-detect a likely type from your changes)
• --scope <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 <url>: Add remote origin if repo is new

Supported Commit Types

• 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

1. Git Repository Management

• Automatic repository detection and initialization
• Smart remote origin setup
• Default branch configuration to main
• Comprehensive repository state validation

2. Intelligent Branch Management

• 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. Automated File Staging

• Detects unstaged changes automatically
• Stages all files when no staged changes found
• Progress feedback during staging operations
• Robust error handling for staging failures

4. Commit Message Generation

• 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 <type> explicitly.

5. Advanced Push and Merge Workflows

• 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

6. Professional User Experience

• 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

Core Dependencies

• @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

Project Configuration

• Package: gitgenie-cli
• Version: 1.0.0+
• Module Type: ES6 modules
• Global Command: gg
• Entry Point: index.js
• Node Version: 16+ recommended

Example Usage & Sample Commands

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:

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

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

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

# 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

Current Workflow Summary

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

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

• Add support for conventional commit scopes validation.

• Implement configuration file for default settings.

• Add git hooks integration for automated workflows.

This document captures the current state of GitGenie CLI, including all features, functionality, CLI behavior, project structure, and comprehensive usage examples. It serves as a complete reference for users and developers working with or extending the tool.