🪄 GitEase

Git commands in plain English, powered by AI

Transform complex Git operations into simple conversations. GitEase uses GitHub Copilot to translate your intentions into the right Git commands—no more Googling syntax or memorizing flags.

✨ Features

• 🤖 AI-Powered: Leverages GitHub Copilot CLI for intelligent command suggestions
• 🎯 Natural Language: Describe what you want in plain English—no syntax required
• 🔄 Multi-Step Workflows: Chain operations like "pull and merge" or "commit and push" — executed sequentially with live status
• ⚡ Conflict Detection: Automatically detects merge conflicts and offers to abort or guide you through resolution
• 🧠 Smart Recovery: If a branch doesn't exist, offers to track from remote or create it — no dead-end errors
• 🛡️ Safety-First: Preview commands and see warnings before execution
• 📊 Smart Context: Shows diffs, status, and logs for dangerous operations
• ⏮️ Undo History: Track every action and reverse mistakes
• 🎨 Beautiful UI: Clean, colored terminal output with progress indicators
• 📚 Educational: Learn Git commands while you work

🤔 Why GitEase?

Before GitEase:

# You forget the exact command
$ git ???

# Google "how to undo last commit keep changes"
# Read Stack Overflow
# Copy-paste command
# Cross your fingers 🤞

With GitEase:

$ gitease "undo my last commit but keep the changes"

# Get the right command instantly
# See exactly what will happen
# Execute with confidence ✨

🎬 Demo

$ gitease "undo my last commit but keep the changes"

Git repository detected (branch: main)

✅ GitHub Copilot available

✨ Copilot suggests:

  $ git reset --soft HEAD~1
   This will undo your last commit while keeping changes staged

⚠️  WARNING  This command can modify commit history

Run this command? (y/N): y

▶ Executing...
✅ Done.

Smart Branch Recovery

$ gitease "move to main"

✨ Copilot suggests:
  $ git checkout main

Run this command? (y/N): y

▶ Executing...
⚠️  Branch "main" doesn't exist locally.
   ✓ Found "main" on remote.
   Create local branch tracking origin/main? (y/N): y
✅ Switched to new branch 'main' tracking remote.

📦 Installation

Prerequisites

Before installing GitEase, you'll need:

• Node.js 18+ - Download here
• GitHub CLI - Install with:

  # macOS
  brew install gh
  
  # Windows
  winget install GitHub.cli
  
  # Linux
  sudo apt install gh
  
  # Or download from: https://cli.github.com/

• GitHub Copilot subscription - Sign up here
  • ✅ Free for students/teachers
  • ✅ Free trial available
  • 💰 $10/month for individuals

Installation Steps

1. Install the CLI:

npm install -g gitease-cli

2. Authenticate with GitHub:

gh auth login
# Follow the prompts to authenticate

3. Enable GitHub Copilot CLI extension:

# On newer GitHub CLI versions, copilot is built-in
# On first use, it will auto-download the Copilot CLI (takes ~30 seconds)
gh copilot --help  # Verify it works

Note: The first time you use gh copilot, it downloads the Copilot CLI automatically. This may take 30-60 seconds. Subsequent calls will be faster.

4. Verify GitEase works:

cd /path/to/your/git/repo
gitease "show recent commits"

⚠️ Troubleshooting

GitEase command not found

# Make sure npm global bin is in PATH
npm config get prefix
# Add ~/.npm-global/bin to your PATH if needed

"Copilot request timed out"

• Make sure gh copilot CLI is installed:

  gh copilot --help

• If it's not working, reinstall:

  gh extension remove github/gh-copilot
  gh extension install github/gh-copilot

"GitHub Copilot not available"

You need an active GitHub Copilot subscription to use GitEase:

• ✅ Free for students and teachers
• ✅ Free trial (2 months)
• 💰 $10/month for individuals
• Sign up at github.com/features/copilot

🚀 Quick Start

# 1. Install GitEase globally
npm install -g gitease-cli

# 2. Authenticate with GitHub (one-time)
gh auth login

# 3. Install Copilot extension and verify
gh extension install github/gh-copilot
gh copilot --prompt "Return just: test"

# 4. Start using it!
gitease "create a new branch called feature-login"

🚀 Usage

Natural Language Queries

GitEase understands plain English descriptions of what you want to do:

# Undo operations
gitease "undo my last commit"
gitease "undo last 3 commits but keep changes"
gitease "undo the commit before last"

# Branch operations  
gitease "create a new branch called feature-auth"
gitease "switch to main and pull latest"
gitease "delete the feature-test branch"

# Viewing history
gitease "show me what changed in the last commit"
gitease "show commit history for the past week"
gitease "who changed this file last"

# Staging and commits
gitease "stage all JavaScript files"
gitease "commit everything with message 'Fix authentication bug'"
gitease "unstage all files"

# Advanced operations
gitease "cherry pick commit abc123"
gitease "interactive rebase last 5 commits"
gitease "squash last 3 commits"

Multi-Step Workflows

GitEase automatically detects compound requests and runs them as a coordinated pipeline:

# Pull & merge in one go
gitease "pull from origin and merge main"

# Stage, commit, and push
gitease "stage everything, commit with message 'fix: resolve auth bug', and push"

# Sync your branch with remote
gitease "fetch and rebase onto main"

# Save and push work
gitease "commit all changes then push to origin"

Workflow output:

🔄 Multi-step workflow detected

📋 Workflow Plan (3 steps):

  1. git add -A
     Stage all changes
  2. git commit -m "fix: resolve auth bug"
     Commit staged changes
  3. git push origin main
     Push commits to remote

Run this workflow? (y/N): y

▶ Running workflow...

[1/3] ✓ git add -A
[2/3] ✓ git commit -m "fix: resolve auth bug"
[3/3] ✓ git push origin main

✅ Workflow completed successfully!

Conflict handling: If a merge or pull causes conflicts, GitEase will:

• Show you exactly which files have conflicts
• Offer to abort the merge
• Or guide you through manual resolution

Built-in Commands

# Check detailed repository status
gitease status

# View command history
gitease history

# Undo last executed command
gitease undo

# Get help
gitease --help
gitease --version

🎯 How It Works

┌─────────────────────────────────┐
│  You type plain English         │
│  "undo my last commit"          │
│  "pull and merge main"          │
└────────────┬────────────────────┘
             ↓
┌─────────────────────────────────┐
│  GitEase validates:             │
│  ✓ Git repository exists        │
│  ✓ GitHub Copilot available     │
│  ✓ Repository has commits       │
└────────────┬────────────────────┘
             ↓
┌─────────────────────────────────┐
│  Workflow detection:            │
│  Single command? → one-shot     │
│  Multi-step? → workflow plan    │
└────────────┬────────────────────┘
             ↓
┌─────────────────────────────────┐
│  GitHub Copilot analyzes        │
│  Suggests command(s)            │
└────────────┬────────────────────┘
             ↓
┌─────────────────────────────────┐
│  GitEase safety check:          │
│  • Analyzes risk level          │
│  • Shows preview/diff           │
│  • Warns about dangers          │
└────────────┬────────────────────┘
             ↓
┌─────────────────────────────────┐
│  You confirm (Y/n)              │
└────────────┬────────────────────┘
             ↓
┌─────────────────────────────────┐
│  Executes sequentially          │
│  Detects conflicts (if any)     │
│  Action saved to history        │
│  Success confirmation shown     │
└─────────────────────────────────┘

🛡️ Safety Model

GitEase categorizes commands by risk level:

🟢 Safe (Auto-execute or minimal confirmation)

• Read-only operations: git status, git log, git diff
• Simple staging: git add
• Branch viewing: git branch --list

🟡 Warning (Show preview + confirmation)

• Merges: git merge
• Rebases: git rebase
• Pushes: git push
• Commits: git commit

🔴 Dangerous (Show detailed preview + strong warning)

• Hard resets: git reset --hard
• Force pushes: git push --force
• Destructive cleanups: git clean -fd
• Branch deletions: git branch -D

Dangerous commands show:

• ⚠️ Clear warning message
• 📋 Preview of what will be affected (diffs, files, commits)
• ❓ Strong confirmation prompt

⏮️ Undo History

GitEase tracks every command you execute in ~/.gitease-ledger.json.

# View your command history
gitease history

Example output:

Recent GitEase Commands:
━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
1. git commit -m "Add authentication"
   📁 /Users/you/projects/my-app
   🕐 2 minutes ago

2. git add src/auth.ts
   📁 /Users/you/projects/my-app  
   🕐 5 minutes ago

3. git checkout -b feature-auth
   📁 /Users/you/projects/my-app
   🕐 10 minutes ago

Undo Last Action

gitease undo

Reversible operations:

• git commit → git reset --soft HEAD~1
• git add <files> → git reset HEAD <files>
• git checkout -b <branch> → git checkout - + git branch -d <branch>
• git merge → git merge --abort (if in progress)

Non-reversible operations:

• git push (changes are on remote)
• git reset --hard (data lost)
• Destructive operations

GitEase will warn you if an operation cannot be undone.

🛠️ Development

Want to contribute or customize GitEase? Here's how to get started.

Clone & Setup

# Clone the repository
git clone https://github.com/simukuka/gitease.git
cd gitease

# Install dependencies
npm install

# Build TypeScript
npm run build

# Link locally for testing
npm link

Now you can use gitease globally on your machine with your local changes.

Development Commands

# Build once
npm run build

# Watch mode (auto-rebuild on changes)
npm run dev

# Run locally without installing
node dist/cli.js "your query"

# Debug mode (verbose logging)
DEBUG=1 gitease "your query"

Adding New Features

Example: Add a new safety check

1. Update src/safety.ts:

export function isDestructive(command: string): boolean {
  const destructivePatterns = [
    /git\s+reset\s+--hard/,
    /git\s+clean\s+-[fd]/,
    // Add your pattern
  ];
  return destructivePatterns.some(p => p.test(command));
}

2. Rebuild and test:

npm run build
gitease "your test query"

🧪 Testing

# Test in a safe repository
cd /tmp
git init test-repo
cd test-repo
git commit --allow-empty -m "Initial commit"

# Test GitEase commands
gitease "undo my last commit"
gitease status
gitease history

Debug Mode

Enable verbose logging to see what's happening:

DEBUG=1 gitease "your query"

Debug output shows:

• Raw Copilot responses
• Parsed commands
• Risk analysis results
• Git command outputs

🤝 Contributing

Contributions are welcome! Whether it's bug fixes, new features, or documentation improvements.

How to Contribute

1. Fork the repository
2. Create a feature branch

   git checkout -b feature/amazing-feature

3. Make your changes
   • Write clear, commented code
   • Follow existing code style
   • Add tests if applicable
4. Commit your changes

   git commit -m "feat: add amazing feature"

5. Push to your fork

   git push origin feature/amazing-feature

6. Open a Pull Request

Development Guidelines

• Use TypeScript types for all functions
• Add JSDoc comments for public functions
• Keep functions small and focused
• Handle errors gracefully
• Test with various Git scenarios

Ideas for Contributions

• 🌍 Multi-language support
• 🎨 Custom themes/color schemes
• 📦 Additional safety checks
• 🔌 Plugin system for custom commands
• 📖 More comprehensive documentation
• 🧪 Automated testing suite
• 🔀 Interactive conflict resolution UI
• 📋 Custom workflow templates

📝 License

MIT © simukuka

See LICENSE file for details.

🙏 Acknowledgments

• Built for: GitHub Copilot CLI Challenge
• Powered by: GitHub Copilot
• Built with:
  • TypeScript - Type-safe JavaScript
  • Commander.js - CLI framework
  • Chalk - Terminal styling
  • simple-git - Git operations

🔗 Links

• Documentation: Full documentation
• Issues: Report a bug
• Discussions: Ask a question
• Changelog: See what's new

💬 Feedback & Support

Found a bug or have a suggestion?
Open an issue and let's make GitEase better together!

⭐ Star this repo if GitEase helps you!

Report Bug · Request Feature · Contribute