# ๐Ÿš€ GIMS - Git Made Simple [![npm version](https://img.shields.io/npm/v/gims.svg)](https://npmjs.org/package/gims) [![npm downloads](https://img.shields.io/npm/dm/gims.svg)](https://npmjs.org/package/gims) [![License: MIT](https://img.shields.io/badge/License-MIT-yellow.svg)](https://opensource.org/licenses/MIT) [![AI Powered](https://img.shields.io/badge/AI-Powered-blueviolet.svg)](https://github.com/s41r4j/gims) [![Node.js](https://img.shields.io/badge/Node.js->=18.18.0-green.svg)](https://nodejs.org) **AI-powered Git CLI that writes your commit messages for you** *Because life's too short for "fix stuff" commits* ๐ŸŽฏ [Installation](#-installation) โ€ข [Quick Start](#-quick-start) โ€ข [Commands](#-commands) โ€ข [AI Setup](#-ai-providers) โ€ข [Configuration](#-configuration)
--- ## โœจ Features - ๐Ÿค– **AI-Generated Commits** โ€” Let AI analyze your changes and write meaningful commit messages - ๐Ÿ“Š **Smart Status** โ€” Enhanced git status with file type detection and insights - ๐Ÿ”„ **Workflow Shortcuts** โ€” Common multi-step operations condensed to single commands - ๐Ÿ“ˆ **Commit Analytics** โ€” Track your commit streak, patterns, and statistics - ๐Ÿ” **Code Review** โ€” Get AI-powered code review before committing - ๐Ÿ›ก๏ธ **Safe Operations** โ€” Built-in safeguards for destructive commands - โšก **Lightning Fast** โ€” Optimized for speed with intelligent caching --- ## ๐Ÿ“ฆ Installation ```bash npm install -g gims ``` **Requirements:** Node.js >= 18.18.0 --- ## โšก Quick Start ```bash # 1. Setup AI provider (choose one) g setup --api-key gemini # ๐Ÿ†“ Free & fast (recommended) g setup --api-key openai # ๐ŸŽฏ High quality g setup --api-key groq # โšก Ultra fast # 2. Start using it! g s # Check status with AI insights g o # AI commit + push (one command!) ``` ### Your New Workflow ```bash # Before (traditional git) git add . git commit -m "trying to think of message..." git push # After (with GIMS) g o # That's it. AI handles the rest. ``` --- ## ๐Ÿ“š Commands ### ๐Ÿง  Core Commands | Command | Alias | Description | |---------|-------|-------------| | `g status` | `g s` | Enhanced status with AI insights & file type emojis | | `g oneshot` | `g o` | Stage all โ†’ AI commit โ†’ Push (full workflow) | | `g local` | `g l` | Stage all โ†’ AI commit (no push) | | `g suggest` | `g sg` | Get AI commit message suggestions | | `g version` | `g v` | Manage project version (S4 system) | | `g whoami` | โ€” | Show system identity & version | | `g wip` | โ€” | Quick work-in-progress commit | ### ๐Ÿ“Š Analytics & Review | Command | Alias | Description | |---------|-------|-------------| | `g review` | `g r` | AI code review with complexity analysis | | `g today` | `g t` | Show all commits made today | | `g stats` | โ€” | Personal statistics: streak, patterns, style | | `g split` | โ€” | AI suggestions for splitting large changesets | ### โšก Workflow Shortcuts | Command | Alias | What it does | |---------|-------|--------------| | `g safe-pull` | `g sp` | Stash โ†’ Pull โ†’ Pop (safe pull with uncommitted changes) | | `g fix` | โ€” | Smart fix for diverged/ahead/behind branches | | `g main` | โ€” | Switch to main/master + pull latest | | `g stash-save` | `g ss` | Quick stash with auto-generated name | | `g stash-pop` | `g pop` | Pop the latest stash | | `g unstage` | `g us` | Unstage all staged files | | `g discard` | `g x` | Discard all changes (requires `--yes`) | ### ๐Ÿ› ๏ธ Git Helpers | Command | Alias | Description | |---------|-------|-------------| | `g last` | โ€” | Show last commit details with diff | | `g conflicts` | โ€” | Conflict resolution helper | | `g cleanup` | `g clean` | Remove local branches deleted from remote | | `g list` | `g ls` | Compact commit history | | `g amend` | `g a` | Amend the previous commit | | `g undo` | `g u` | Undo last commit (keep changes) | | `g delete-branch` | `g del` | Delete branch locally and remotely | ### ๐Ÿ”ข S4 Versioning (New) GIMS now uses the **S4 Versioning System**, a forensic-grade versioning standard stored entirely in **Git Tags**. `MAJOR.MINOR.PATCH-STAGE.BUILD+DATE.TIME.COMMIT.BRANCH` *(e.g., `0.8.2-dev.1+20250129.1305.af8d9c.main`)* | Command | Description | |---------|-------------| | `g v` | Smart bump (resets build on new day) + Create Tag | | `g v -n` | Dry run (preview next version) | | `g v major` | Force major bump (`1.0.0` โ†’ `2.0.0`) | | `g v --list` | List stable releases (hides dev tags) | | `g v --prune` | Delete old `dev` tags (keeps last 10) | | `g v -i` | Version analysis with timestamp | | `g whoami` | Dynamic identity & version banner | > **Note:** S4 uses Git Tags as the Single Source of Truth. No `VERSION` file is created. It updates your `.env` version variables if they exist. ### ๐Ÿ”ง Setup & Config | Command | Description | |---------|-------------| | `g setup` | Interactive setup wizard | | `g setup --api-key ` | Quick API key setup | | `g config --list` | View all settings | | `g config --set key=value` | Update configuration | | `g quick-help` / `g q` | Quick command reference | --- ## ๐Ÿค– AI Providers GIMS supports multiple AI providers. Choose based on your needs: | Provider | Model | Speed | Quality | Cost | |----------|-------|-------|---------|------| | **Gemini** | `gemini-3-flash-preview` | โšกโšกโšก | โญโญโญ | ๐Ÿ†“ Free | | **Groq** | `groq/compound` | โšกโšกโšกโšก | โญโญโญ | ๐Ÿ†“ Free tier | | **OpenAI** | `gpt-5.2-2025-12-11` | โšกโšก | โญโญโญโญ | ๐Ÿ’ฐ Paid | ### Setting Up API Keys #### Option 1: Interactive Setup (Recommended) ```bash g setup --api-key gemini # Guided setup with instructions g setup --api-key openai g setup --api-key groq ``` #### Option 2: Environment Variables (Auto-detected) GIMS automatically detects API keys from environment variables. Add to your shell profile (`~/.zshrc`, `~/.bashrc`, etc.): ```bash # Gemini (recommended - free) export GEMINI_API_KEY="your-api-key-here" # OpenAI export OPENAI_API_KEY="your-api-key-here" # Groq export GROQ_API_KEY="your-api-key-here" ``` Then reload your shell: `source ~/.zshrc` > **๐Ÿ’ก Tip:** If multiple API keys are set, GIMS auto-selects in order: Gemini โ†’ OpenAI โ†’ Groq ### Getting API Keys
๐Ÿ”ท Gemini (Recommended) 1. Visit [Google AI Studio](https://aistudio.google.com/app/apikey) 2. Create a new API key 3. Set it: `export GEMINI_API_KEY="your-key"` or run `g setup --api-key gemini`
๐ŸŸข Groq 1. Visit [Groq Console](https://console.groq.com/keys) 2. Create a new API key 3. Set it: `export GROQ_API_KEY="your-key"` or run `g setup --api-key groq`
๐ŸŸก OpenAI 1. Visit [OpenAI Platform](https://platform.openai.com/api-keys) 2. Create a new API key 3. Set it: `export OPENAI_API_KEY="your-key"` or run `g setup --api-key openai`
--- ## ๐Ÿ”ง Configuration ```bash # View current settings g config --list # Enable conventional commits (feat:, fix:, etc.) g config --set conventional=true # Auto-stage all changes before commit g config --set autoStage=true # Disable clipboard copy g config --set copy=false # Show/hide progress indicators g config --set progressIndicators=true ``` ### Configuration Options | Option | Type | Default | Description | |--------|------|---------|-------------| | `provider` | string | `auto` | AI provider: `gemini`, `openai`, `groq`, `auto`, `none` | | `model` | string | โ€” | Override default model for provider | | `conventional` | boolean | `false` | Use Conventional Commits format | | `autoStage` | boolean | `false` | Auto-stage all changes | | `copy` | boolean | `true` | Copy suggestions to clipboard | | `progressIndicators` | boolean | `true` | Show progress spinners | --- ## ๐Ÿ“– Usage Examples ### Daily Workflow ```bash g s # Check what's changed g sp # Safe pull (won't lose uncommitted work) # ... do your work ... g o # Commit everything with AI message + push ``` ### Code Review Before Commit ```bash g r # Get AI review of your changes g o # Commit if review looks good ``` ### Handling Branch Issues ```bash g fix # See sync status and options g fix --ai # Get AI recommendation g fix --merge # Merge remote changes g fix --rebase # Rebase onto remote ``` ### Working with Stashes ```bash g ss # Quick stash g main # Switch to main and pull # ... check something ... g pop # Get your work back ``` ### Large Changeset ```bash g split # Get suggestions for splitting changes g sg --multiple # Get multiple commit message options ``` --- ## ๐Ÿ†š GIMS vs Plain Git | Task | Git | GIMS | |------|-----|------| | Commit & push | `git add . && git commit -m "msg" && git push` | `g o` | | Pull with uncommitted changes | `git stash && git pull && git stash pop` | `g sp` | | Check status | `git status` | `g s` (+ AI insights) | | Fix diverged branch | Multiple commands + decisions | `g fix --ai` | | Code review | External tool | `g r` | --- ## ๐Ÿ†˜ Getting Help ```bash g --help # Full command list with descriptions g q # Quick reference card g -h # Help for specific command ``` --- ## ๐Ÿค Contributing Contributions are welcome! Feel free to: - ๐Ÿ› Report bugs - ๐Ÿ’ก Suggest features - ๐Ÿ”ง Submit pull requests --- ## ๐Ÿ“„ License MIT ยฉ [S41R4J](https://github.com/s41r4j) ---
**[โฌ† Back to Top](#-gims---git-made-simple)** Made with โค๏ธ for developers who'd rather code than write commit messages