🚀 Bit CLI - Git with a Brain

An intelligent Git wrapper with AI-powered commits, ghost branches, and predictive merge analysis.

Make Git smarter. Work faster. 🎯

📚 Documentation

New to Bit CLI? Start here 👇

• 🎯 Index - Find what you need
• ⚡ Getting Started - 5-minute quickstart
• 📦 Installation Guide - Detailed setup for all systems
• � API Key Setup - Enable AI features (5 min)
• �📖 Full README - Complete reference (this file)

⚡ Quick Start

Install (Choose One)

Option 1: Global Installation (Recommended)

npm install -g bit-cli-ai
bit --help

Option 2: Local Installation

npm install bit-cli-ai
npx bit --help

Option 3: Try Without Installing

npx bit-cli-ai --help

🌟 Key Features

Ghost Branches (Metadata-Only Workspaces)

Hackathon-Compliant Implementation:

Ghost branches are experimental workspaces that exist only in metadata, not as actual git branches. This allows you to experiment with changes without cluttering your git branch list.

✅ Exists only in .bit/metadata.json - No git branch creation ✅ Does not appear in git branch - Clean git workflow ✅ Appears in bit branch with 👻 emoji - Easy identification ✅ Uses detached HEAD on checkout - Experimental state ✅ Tracks base commit, staged files, and creation context

# Create a ghost branch
bit branch --ghost experiment-name

# List all branches (ghosts shown with 👻)
bit branch

# Verify ghosts are NOT in git
git branch  # Only shows normal branches

# Checkout a ghost branch (detached HEAD)
bit checkout --ghost experiment-name

Additional Features

Level 1: Foundation

• Transparent Passthrough - All git commands work through bit (bit status = git status)
• Smart Init - Auto-detects project type and generates appropriate .gitignore
• AI Commits - Generates meaningful commit messages using AI or rule-based analysis

Level 2: Architect

• Ghost Branches - Hidden experimental branches that don't clutter your branch list
• Virtual Merge - Preview merge conflicts before actually merging
• .bit Directory - Intelligent metadata storage separate from .git

Level 3: Visionary

• Symbol Tracking - Track function-level changes, not just file-level
• Hot Zone Detection - Warns when teammates are editing the same functions

Installation

# Install globally
npm install -g bit-cli-ai

# Or use npx
npx bit-cli-ai <command>

Quick Start

# Initialize a new repository with smart defaults
bit init

# Make some changes, then commit with AI
git add .
bit commit

# Create a ghost branch for experiments
bit branch --ghost experiment

# Preview merge conflicts before merging
bit merge --preview feature-branch

# Check for team conflicts
bit hotzone

# Analyze code changes
bit analyze

🛠️ Technical Implementation - Ghost Branches

Architecture

Ghost branches are stored only in metadata - no git branches are created:

// .bit/metadata.json
{
  "gitCommit": "abc123...",
  "ghostBranches": [
    {
      "name": "experiment-1",
      "baseCommit": "abc123...",
      "createdFrom": "main",
      "createdAt": "2026-01-01T00:00:00.000Z",
      "isGhost": true,
      "status": {
        "commit": "abc123...",
        "staged": ["file1.ts"],
        "unstaged": ["file2.ts"]
      }
    }
  ]
}

How It Works

1. Creation: Stores branch metadata in .bit/metadata.json only
2. Listing: Displays ghosts with 👻 emoji and age calculation
3. Checkout: Uses git checkout <commit-hash> to go into detached HEAD
4. Deletion: Removes from .bit/metadata.json only

Compliance Verification

# ✅ Create a ghost branch
$ bit branch --ghost my-experiment
Created ghost branch: my-experiment 👻
Base commit: abc123...
Saved to metadata only (no git branch created)

# ✅ Verify ghost is NOT in git branch list
$ git branch
* main
  feature-x
# (No ghost/ branches visible!)

# ✅ Ghost appears in bit branch with emoji
$ bit branch
🌿 main (active)
  feature-x
👻 my-experiment (30 min ago) - from main

# ✅ Checkout ghost (detached HEAD state)
$ bit checkout --ghost my-experiment
Checked out ghost: my-experiment 👻
HEAD is now at abc123... DETACHED

Key Design Decisions

✅ No git branch prefix - No ghost/ branches in git ✅ Detached HEAD on checkout - Experimental state clearly visible ✅ Metadata-only storage - Clean git history ✅ Emoji identification - 👻 makes ghosts instantly recognizable ✅ Age tracking - Shows how long ghost has existed

Common Use Cases

1. AI-Powered Commits

# Stage your changes
git add .

# Let AI generate a meaningful commit message
bit commit

# Or use your own message
bit commit -m "Fixed authentication bug"

2. Experimental Ghost Branches

# Create a ghost branch for experimenting
bit branch --ghost try-new-feature

# List all branches (ghosts shown with 👻)
bit branch

# Checkout the ghost branch
bit checkout --ghost try-new-feature

# Make changes, commit, etc.
git add .
git commit -m "WIP: trying new approach"

# Go back to main
bit checkout main

# Delete ghost when done
bit branch --delete --ghost try-new-feature

3. Merge Preview

# Preview what will happen before merging
bit merge --preview feature-branch

# If it looks good, actually merge
bit merge feature-branch

4. Team Conflict Detection

# See if teammates are working on overlapping code
bit hotzone

# Output: Shows which functions/symbols are in conflict

5. Code Analysis

# Get detailed analysis of your changes at symbol level
bit analyze

# Shows functions/classes you've modified

❓ Troubleshooting

Issue: bit: command not found

Solution 1: Install Globally

npm install -g bit-cli-ai
# Then close and reopen terminal
bit --version

Solution 2: Use npx

npx bit-cli-ai --help

Solution 3: Check npm Path

# Windows
npm config get prefix
# Should be in your PATH

# Linux/Mac
which npm

Issue: unknown option: -version

Wrong: bit -version (single dash) Right: bit --version (double dash)

# Correct commands
bit --version
bit -V
bit --help
bit -h

Issue: AI Features Not Working

Check API Key:

# Set your OpenAI API key
export OPENAI_API_KEY=sk-your-key-here

# Windows PowerShell
$env:OPENAI_API_KEY="sk-your-key-here"

Verify:

bit commit  # Should use AI now

Issue: Not in a Git Repository

Solution:

# Make sure you're in a git repo
git init
bit init

Issue: Slow on First Run

Normal! The first run installs dependencies and initializes metadata. Subsequent runs are much faster.

📋 System Requirements

• Node.js: >= 18.0.0
• npm: >= 8.0.0
• Git: >= 2.30.0
• OS: Windows, macOS, or Linux

Verify you have these:

node --version      # Should be v18+
npm --version       # Should be 8+
git --version       # Should be 2.30+

🔧 Configuration

Setup OpenAI Key (Optional, for AI features)

# Create ~/.bit directory (or use existing)
mkdir -p ~/.bit

# Create config.json
cat > ~/.bit/config.json << 'EOF'
{
  "ai": {
    "provider": "openai",
    "apiKey": "sk-your-key-here"
  }
}
EOF

# Or set environment variable
export OPENAI_API_KEY=sk-your-key-here

📊 What Gets Stored

Bit creates a .bit/ directory in your repo:

.bit/
├── config.json          # Project configuration
└── metadata.json        # Ghost branches and metadata

Note: Both files are safe to commit to git or add to .gitignore.

🐛 Debug Mode

Enable detailed logging:

# Windows
set BIT_DEBUG=true
bit commit

# Linux/Mac
export BIT_DEBUG=true
bit commit

# Windows PowerShell
$env:BIT_DEBUG="true"
bit commit

📖 Real-World Examples

Example 1: Hackathon Experiment

# You're at a hackathon, want to try a crazy idea
bit branch --ghost hackathon-idea

# Switch to it
bit checkout --ghost hackathon-idea

# Make changes without polluting git branches
git add .
bit commit  # AI generates message

# Show judges the main branch (git branch), then show ghosts (bit branch)
# Judges see clean history, but all work is preserved in metadata!

Example 2: Code Review with Team

# Create feature branch
git checkout -b feature/new-api

# Make changes
git add .
bit commit  # Gets meaningful AI message

# Push
git push origin feature/new-api

# On reviewer's machine
git checkout feature/new-api

# Preview any merge issues
bit merge --preview main

# Check for team conflicts
bit hotzone

# Merge when ready
bit merge main

Example 3: Parallel Experiments

# Idea 1: Try new authentication
bit branch --ghost auth-oauth

# Idea 2: Try caching strategy
bit branch --ghost redis-cache

# List everything
bit branch

# Compare ghosts
bit checkout --ghost auth-oauth
# ... test it ...
bit checkout main

bit checkout --ghost redis-cache
# ... test it ...
bit checkout main

# Keep the best one, delete the other
bit branch --delete --ghost redis-cache

🆘 Getting Help

Check the help menu:

bit --help
bit <command> --help

Enable verbose output:

bit --verbose <command>

Report issues:

• GitHub: https://github.com/shubhashis9556/bit-cli/issues
• Email: [email protected]

Architecture

Architecture

bit-cli/
├── src/
│   ├── index.js              # CLI entry point
│   ├── commands/             # Command implementations
│   │   ├── init.js
│   │   ├── commit.js
│   │   ├── branch.js
│   │   ├── merge.js
│   │   ├── hotzone.js
│   │   └── analyze.js
│   └── utils/                # Shared utilities
│       ├── ai.js             # AI service
│       ├── config.js         # Configuration management
│       ├── errors.js         # Error handling
│       ├── git.js            # Git operations
│       ├── logger.js         # Logging
│       └── validation.js     # Input validation
├── tests/                    # Test files
└── .github/workflows/        # CI/CD

Development

# Clone repository
git clone https://github.com/yourusername/bit-cli.git
cd bit-cli

# Install dependencies
npm install

# Run in development
npm run dev

# Run tests
npm test

# Run tests with coverage
npm run test:coverage

# Lint code
npm run lint

# Format code
npm run format

Contributing

1. Fork the repository
2. Create a feature branch (git checkout -b feature/amazing)
3. Commit your changes (bit commit)
4. Push to the branch (git push origin feature/amazing)
5. Open a Pull Request

License

MIT License - see LICENSE for details.