npm package: @abhijitgobe/git-ai
Description: AI-powered CLI tool that generates meaningful, conventional commit messages using Google's Gemini API. Zero-to-Hero: auto-init repos, create GitHub repos, and push with a single command!
Author: Abhijit Gobe
Latest version: 2.0.2

# 🤖 git-ai

**All-in-one CLI for automating GitHub workflows**

Complete GitHub automation in one tool: create & initialize repositories, commit changes, push to GitHub, manage remotes, generate documentation, and share on social media. For commits, it uses Google Gemini 2.0 Flash AI to analyze your code and generate smart, conventional commit messages automatically.

## ✨ What git-ai Does

**Core Automation Features:**
- 🚀 **Zero-to-Hero Mode**: One command to initialize git, detect project type, create `.gitignore`, generate README.md, commit, and push to GitHub
- 🔄 **GitHub Automation**: Create repositories, push commits, manage remotes — all from the CLI
- 📁 **Project Detection**: Automatically identifies 9+ project types (Node.js, Python, Rust, Go, Java, .NET, Ruby, PHP, Flutter)
- 📝 **Auto-Generated Docs**: Creates stack-specific `.gitignore` files and AI-powered README.md
- 🌍 **Social Media Integration**: `git-ai share` generates ready-to-post Twitter/LinkedIn content
- 🔐 **Secure OAuth**: GitHub authentication via Device Flow — no passwords, tokens stored securely

**Smart Commit Generation (powered by Gemini 2.0 Flash AI):**
- 🧠 **AI Analysis**: Analyzes your code changes using Google Gemini 2.0 Flash
- 📋 **Conventional Format**: Generates commits following conventional commit standards (feat, fix, docs, chore, etc.)
- ⚡ **Smart Defaults**: Auto-stages changes, auto-pushes when remote exists, interactive review mode
- ✏️ **Customizable**: Review, edit, or regenerate messages before committing

**Configuration & Control:**
- ⚙️ **Config Management**: Easy command-line control for API keys and preferences
- 🎛️ **Model Selection**: Choose different Gemini models or customize AI behavior
- 🔒 **Security First**: All credentials stored securely, nothing exposed in logs

## 📦 Installation

```bash
npm install -g @ag/git-ai
```

> Note: This is a shorthand alias. Full name is `@abhijitgobe/git-ai`

After installation, run the setup wizard:

```bash
git-ai setup
```

This will guide you through:
1. Configuring your Gemini API key (free from Google AI Studio)
2. Then authenticate with GitHub via Device Flow

Then login to GitHub:

```bash
git-ai login
```

This opens your browser for secure OAuth authentication (no passwords).

## 🚀 Quick Start

### For existing projects with changes:

```bash
git add .  # or git add <specific-files>
git-ai
```

That's it! It will:
1. Analyze the staged diff with AI
2. Generate a smart commit message
3. Let you review/edit/commit
4. Auto-push if remote exists

### For brand new projects (Zero-to-Hero):

```bash
mkdir my-awesome-project
cd my-awesome-project
echo "# My Awesome Project" > README.md
git-ai -i --yes
```

This single command will:
1. Initialize a git repository
2. Detect your project type (Node.js, Python, Rust, etc.)
3. Generate stack-specific `.gitignore`
4. Create AI-generated `README.md`
5. Generate an AI commit message
6. Create initial commit
7. Create a GitHub repository (via OAuth)
8. Push to GitHub

**Result:** Your project is live on GitHub with a professional README and meaningful commit history!

### Generate social media posts:

```bash
git-ai share
```

Generates Twitter and LinkedIn posts with repository link — ready to copy & share!

## 📖 Usage

### Main Commands

**GitHub Automation:**
```bash
# Initialize new project + push to GitHub (Zero-to-Hero mode)
git-ai -i --yes

# Create public repo (default is private)
git-ai -i --yes --public
```

**Commit Generation (with Gemini AI):**
```bash
# Generate commit with AI (interactive, review before committing)
git-ai

# Auto-commit without review
git-ai --yes

# Stage all changes + generate commit
git-ai -a
```

**GitHub & Auth:**
```bash
# Login to GitHub (OAuth Device Flow)
git-ai login

# Logout from GitHub
git-ai logout
```

**Social Media:**
```bash
# Generate Twitter/LinkedIn posts
git-ai share
```

**Configuration:**
```bash
# Run setup wizard
git-ai setup

# Manage config
git-ai config set GEMINI_API_KEY=your_key
git-ai config get GEMINI_API_KEY
git-ai config list
git-ai config path
```

### All Options

| Flag | Description |
|------|-------------|
| `-i, --init` | Zero-to-Hero mode: init repo, create GitHub repo, commit, push |
| `-y, --yes` | Skip confirmation, auto-commit immediately |
| `-a, --all` | Stage all changes before generating commit |
| `-p, --push` | Push to remote after committing |
| `--public` | Create public GitHub repo (default: private) |
| `--private` | Create private GitHub repo |
| `-m, --model` | Specify Gemini model (default: gemini-2.0-flash) |
| `-v, --version` | Show version |
| `--help` | Show help for any command |

## 🔧 Requirements

- **Node.js** >= 18.0.0
- **Git** installed and configured with `git config user.name` and `git config user.email`
- **Gemini API Key** (free from [Google AI Studio](https://aistudio.google.com/app/apikey))
- **GitHub Account** (for repo creation and OAuth)

## 🔑 Getting a Gemini API Key

1. Go to [Google AI Studio](https://aistudio.google.com/app/apikey)
2. Sign in with your Google account
3. Click "Create API Key"
4. Copy the key
5. Run `git-ai setup` and paste the key when prompted

**Free Tier:** Generous free tier for personal projects — no credit card needed!

## 🔐 GitHub Authentication (OAuth Device Flow)

git-ai uses **OAuth Device Flow** for secure GitHub authentication:

1. Run `git-ai login`
2. Browser opens automatically (or manual link provided)
3. Approve the request on GitHub
4. Token stored securely in your system config (never exposed)
5. Ready to create repos!

**No passwords, no personal access tokens in your environment.**

## 🏗️ How Zero-to-Hero Works

**The Complete Workflow - All in One Command:**

When you run `git-ai -i --yes` in a new project:

```
Step 1/6: Initialize git repository
          ✅ Creates .git directory

Step 2/6: Detect project type
          ✅ Identifies Node.js, Python, Rust, etc.

Step 3/6: Generate .gitignore
          ✅ Stack-specific ignore rules created

Step 4/6: Generate README.md
          ✅ AI-powered documentation generated (using Gemini)

Step 5/6: Create initial commit
          ✅ AI-generated commit message (using Gemini 2.0 Flash)
          ✅ Example: "feat: initial project setup"

Step 6/6: Create GitHub repo & push
          ✅ GitHub repository created via OAuth
          ✅ Changes pushed to remote
          ✅ Your project is now live!

✅ Result: Professional project on GitHub, ready to share!
```

This is **complete GitHub automation** — one command does all 6 steps automatically.

## 📊 Supported Project Types

Automatically detected and configured with proper `.gitignore` rules:

- **Node.js** (package.json)
- **Python** (requirements.txt, setup.py)
- **Rust** (Cargo.toml)
- **Go** (go.mod)
- **Java** (pom.xml, build.gradle)
- **.NET** (*.csproj)
- **Ruby** (Gemfile)
- **PHP** (composer.json)
- **Flutter** (pubspec.yaml)

## 🚀 What You Can Do

### 1. Smart Commit Generation
```bash
git add .
git-ai --yes
# Generates meaningful commit from your changes
```

### 2. Automate New Projects (Zero-to-Hero)
```bash
mkdir my-project && cd my-project
echo "# My Project" > README.md
git-ai -i --yes
# Repo initialized, committed, and pushed to GitHub in seconds!
```

### 3. Generate Documentation
- **README.md**: AI-generated from your project files
- **.gitignore**: Stack-specific rules automatically included

### 4. Social Media Sharing
```bash
git-ai share
# Get Twitter/LinkedIn posts ready to share
```

### 5. GitHub Automation
- Create repositories directly from CLI
- Push commits automatically
- Manage remotes seamlessly

## 📈 Performance

- **Startup Time**: <100ms
- **Commit Generation**: ~2 seconds
- **Zero-to-Hero Setup**: ~8 seconds
- **Bundle Size**: 70.41 KB
- **Success Rate**: 100% (84/84 tests passing)

## 🔒 Security & Privacy

- ✅ API keys stored securely in system config (not in code)
- ✅ GitHub OAuth tokens never logged or exposed
- ✅ No credentials in environment variables
- ✅ Local processing only (no data sent to third parties except APIs)
- ✅ Conventional commits format ensures consistency
- ✅ Full transparency in what git-ai does

## 📝 Examples

### Example 1: Feature Development
```bash
# Make changes
echo "function notify() { console.log('Notified'); }" >> src/index.js

# Commit with AI
git add src/index.js
git-ai --yes

# Output: "feat: add notification system"
# Automatically pushed to GitHub!
```

### Example 2: New Python Project
```bash
mkdir data-analyzer
cd data-analyzer
echo "import pandas" > main.py
git-ai -i --yes

# Creates: git repo, .gitignore (Python-specific), README.md
# Commits: "feat: initial project setup"
# Pushes to: https://github.com/yourname/data-analyzer
```

### Example 3: Bug Fix
```bash
# Fix a bug
git add .
git-ai  # Interactive mode - review message before commit

# Output shows: "fix: resolve null pointer exception in parser"
```

## 🤝 Contributing

Contributions are welcome! Please feel free to submit a Pull Request.

## 📄 License

MIT © Abhijit Gobe

---

Made with ❤️ and AI