🪄 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:
``bash


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:
`bash
$ gitease "undo my last commit but keep the changes"

Get the right command instantly

See exactly what will happen

Execute with confidence ✨

`

---

🎬 Demo

`bash
$ 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.
`

$3


`bash
$ 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

$3

Before installing GitEase, you'll need:

- Node.js 18+ - Download here
- GitHub CLI - Install with:
`bash
# 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

$3

1. Install the CLI:
`bash
npm install -g gitease-cli
`

2. Authenticate with GitHub:
`bash
gh auth login


Follow the prompts to authenticate


`

3. Enable GitHub Copilot CLI extension:
`bash


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:
`bash
cd /path/to/your/git/repo
gitease "show recent commits"
`

---

⚠️ Troubleshooting

$3


`bash

Make sure npm global bin is in PATH

npm config get prefix

Add ~/.npm-global/bin to your PATH if needed

`

$3

- Make sure gh copilot CLI is installed:
`bash
gh copilot --help
`
- If it's not working, reinstall:
`bash
gh extension remove github/gh-copilot
gh extension install github/gh-copilot
`

$3

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

`bash

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

$3

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


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"
`

$3

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

`bash


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

$3


`bash

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:

$3

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

$3

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

$3

- 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.
`bash


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
`

$3


`bash
gitease undo
`

Reversible operations:
- git commit → git reset --soft HEAD~1
- git add → git reset HEAD
- git checkout -b → git checkout - + git branch -d
- 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.

$3


`bash

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.

$3


`bash

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"
`

$3

Example: Add a new safety check

1. Update src/safety.ts:
`typescript
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:
`bash
npm run build
gitease "your test query"
`

---

🧪 Testing


`bash

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
`

$3

Enable verbose logging to see what's happening:
`bash
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.

$3

1. Fork the repository
2. Create a feature branch
`bash
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
`bash
git commit -m "feat: add amazing feature"
`
5. Push to your fork
`bash
git push origin feature/amazing-feature
``
6. Open a Pull Request

$3

- 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

$3

- 🌍 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!

---