GitClean CLI 🚀

A beautiful CLI tool for creating clean, conventional git commits with real-time spell checking and seamless git workflow automation

✨ Features

🎯 Complete Git Workflow: Single command to stage, commit, and push changes
📝 Interactive Commit Builder: Guided prompts for creating well-structured commits
🔍 Real-time Spell Checking: Live spell checking as you type with visual feedback
🎨 Conventional Commits: Enforces conventional commit standards with emojis
🌟 Beautiful Terminal UI: Colorful interface with boxes, spinners, and progress indicators
🔧 Git Hook Integration: Seamless integration with git's prepare-commit-msg hook
⚡ Smart Defaults: Works out of the box with zero configuration
🧪 Built-in Testing Tools: Test spell checker and see how it works

🚀 Quick Start

Installation

# Install globally (recommended)
npm install -g gitcleancommit

# Or use with npx (no installation)
npx gitcleancommit

# Or install as a dev dependency
npm install --save-dev gitcleancommit

Basic Usage

# Run the complete workflow (add → commit → push)
gitclean

# That's it! GitClean will handle everything else 🎉

📋 Commands

`gitclean` (default)

The main command that runs the complete git workflow:

Shows the GitClean banner
Checks for uncommitted changes
Guides you through creating a conventional commit
Stages all changes (git add .)
Creates the commit
Pushes to the current branch

gitclean

`gitclean commit`

Create a commit without the full workflow (no automatic staging or pushing):

gitclean commit

# Hook mode (used internally by git hooks)
gitclean commit --hook <commit-msg-file>

`gitclean setup` / `gitclean install`

Install GitClean as a git hook in your repository:

gitclean setup
# or
gitclean install

This creates a prepare-commit-msg hook that automatically runs GitClean when you use git commit.

`gitclean uninstall` / `gitclean remove`

Remove GitClean git hooks from your repository:

gitclean uninstall
# or
gitclean remove

`gitclean status` / `gitclean s`

Display the current git status:

gitclean status
# or
gitclean s

`gitclean spellcheck` / `gitclean spell`

Test the spell checker with custom text:

# Basic spell check
gitclean spellcheck "your text here"

# Verbose mode - shows dictionary stats
gitclean spellcheck "your text" --verbose
gitclean spellcheck "your text" -vr

`gitclean test`

Run the built-in spell checker test suite with common development terms:

gitclean test

`gitclean --version` / `gitclean -v`

Show the current version:

gitclean --version
# or
gitclean -v

🎨 Commit Types

GitClean supports six conventional commit types, each with its own color and emoji:

Type	Emoji	Color	Description	Example
`ADD`	➕	Green	Add new code, features, or files	`ADD: user authentication module`
`FIX`	🐛	Red	Fix bugs or issues	`FIX: resolve memory leak in parser`
`UPDATE`	🔄	Yellow	Update existing code or features	`UPDATE: improve error handling`
`DOCS`	📚	Blue	Documentation changes only	`DOCS: add API usage examples`
`TEST`	✅	Cyan	Add or update tests	`TEST: add unit tests for validators`
`REMOVE`	🗑️	Bright Red	Remove code, files, or features	`REMOVE: deprecated API endpoints`

🔍 Real-time Spell Checking

GitClean features an advanced spell checker specifically optimized for development:

Features

Live Feedback: See misspellings highlighted in red as you type
Smart Dictionary: Recognizes 200+ technical terms and programming keywords
Common Typo Detection: Automatically catches and suggests fixes for common developer typos
Visual Indicators: Misspelled words are underlined in red during input

Technical Dictionary

The spell checker recognizes common development terms including:

Programming languages: javascript, typescript, python, java, etc.
Frameworks: react, vue, angular, nodejs, webpack, etc.
Git terms: commit, merge, rebase, checkout, etc.
DevOps: docker, kubernetes, ci/cd, aws, azure, etc.
Web terms: api, http, cors, jwt, oauth, etc.
And 150+ more technical terms!

Common Typo Corrections

Automatically detects and corrects common programming typos:

fucntion → function
recieve → receive
occured → occurred
seperate → separate
componnet → component
databse → database
And 100+ more patterns!

💡 Usage Examples

Basic Commit Workflow

$ gitclean

  GitClean Banner (ASCII Art)
  Clean, conventional commits made easy

🔍 Found changes to commit
This will: git add . → git commit → git push

🔤 Real-time spell checking enabled for text inputs!

? Select the type of change you're committing: (Use arrow keys)
❯ ADD          - Add new code or files
  FIX          - A bug fix
  UPDATE       - Updated a file or code
  DOCS         - Documentation changes
  TEST         - Adding tests
  REMOVE       - Removing code or files

Commit with Scope

Add a scope to categorize your commits:

? What is the scope of this change? (optional): auth
? Write a short, imperative tense description: implement JWT token validation

# Results in: ADD(auth): implement JWT token validation

Breaking Changes

Mark commits that introduce breaking changes:

? Are there any breaking changes? Yes

# Adds "BREAKING CHANGE:" to the commit body
# Results in: ADD(auth)!: new authentication system

Issue References

Link commits to issues:

? Add issue references: fixes #123, closes #456

# Adds issue references to the commit body

Complete Example

$ gitclean

# After answering all prompts:

┌─ Final Commit Message ──────────────────────────────────┐
│ ➕ ADD(auth): implement JWT token validation            │
│                                                         │
│ Added secure token validation with refresh capability   │
│                                                         │
│ 💥 BREAKING CHANGE: implement JWT token validation      │
│                                                         │
│ fixes #123, closes #456                                 │
└─────────────────────────────────────────────────────────┘

? Ready to commit? Yes

🚀 Starting GitClean workflow...

✔ Files added: .
✔ Commit created successfully!
✔ Pushed to main successfully!

✅ GitClean workflow completed successfully!
📦 Changes pushed to main

🧪 Testing the Spell Checker

Interactive Testing

Test the spell checker with your own text:

$ gitclean spellcheck "Fix fucntion that handls user authetication"

🔍 Checking spelling...

┌─ Spell Check Results ───────────────────────────────────┐
│ ⚠️  Spelling issues found:                              │
│                                                         │
│ Original: Fix fucntion that handls user authetication   │
│ Corrected: Fix function that handles user authentication│
│                                                         │
│ 📝 Issues found:                                        │
│ • fucntion → function                                   │
│ • handls → handles                                      │
│ • authetication → authentication                        │
└─────────────────────────────────────────────────────────┘

Verbose Mode

See detailed spell checker statistics:

$ gitclean spellcheck --verbose

┌─ Spell Checker Status ──────────────────────────────────┐
│ 📊 Spell Checker Information                            │
│                                                         │
│ Initialized: ✅                                         │
│ Dictionary: ✅ Loaded                                   │
│ Technical words: 200+                                   │
│ Typo correction rules: 100+                             │
│                                                         │
│ This spell checker is optimized for:                   │
│ • Git commit messages                                   │
│ • Programming terminology                               │
│ • Common development terms                              │
│ • Technical abbreviations                               │
└─────────────────────────────────────────────────────────┘

Run Test Suite

Run the built-in test suite:

$ gitclean test

┌─ Spell Checker Test Suite ──────────────────────────────┐
│ 🧪 Running Spell Checker Tests                          │
│                                                         │
│ Testing with common development-related text...         │
└─────────────────────────────────────────────────────────┘

1. Testing: "Fix typo in fucntion name"
   ❌ Found 1 issue(s)
   🔧 Corrected: "Fix typo in function name"

2. Testing: "Add new componnet for user managment"
   ❌ Found 2 issue(s)
   🔧 Corrected: "Add new component for user management"

# ... more test cases ...

┌─ Test Results ──────────────────────────────────────────┐
│ ✅ Test completed!                                      │
│                                                         │
│ Dictionary status: Active                               │
│ Total technical terms: 200+                             │
│ Total typo rules: 100+                                  │
└─────────────────────────────────────────────────────────┘

🔧 Git Hook Integration

Automatic Setup

Install GitClean as a git hook to use it with standard git commands:

# Install the hook
gitclean setup

# Now use git commit as usual
git add .
git commit  # GitClean will automatically run!

Manual Removal

Remove the git hook if needed:

gitclean uninstall

How It Works

The git hook integration:

Creates a prepare-commit-msg hook in .git/hooks/
Runs GitClean automatically when you use git commit
Only activates for empty commit messages
Doesn't interfere with merge commits or rebases

⚙️ Configuration

GitClean works with zero configuration! However, here are some behaviors to note:

Default Behaviors

File Staging: By default runs git add . (all files)
Push Target: Pushes to the current branch on origin
Spell Check: Enabled by default for all text inputs
Commit Format: Follows conventional commit standards

Requirements

Node.js: Version 18.0.0 or higher
Git: Must be installed and configured
Terminal: Supports color output and Unicode

🛠️ Advanced Features

Escape Key Handling

Press ESC at any time during the prompts to safely cancel the operation:

┌─ Operation Cancelled ───────────────────────────────────┐
│ ⚠️  Operation cancelled by user (ESC pressed)           │
│                                                         │
│ Run the command again when you're ready to commit.     │
└─────────────────────────────────────────────────────────┘

Smart Change Detection

GitClean automatically detects if you have changes to commit:

$ gitclean
⚠️  No changes to commit
Make some changes and run `gitclean` again

💡 Try these commands:
• gitclean spellcheck "your text" - Test spell checker
• gitclean test - Run spell checker tests
• gitclean setup - Install git hooks

Error Handling

GitClean provides clear error messages and recovery suggestions:

Not in a git repository: Suggests running git init
No remote repository: Suggests adding a remote
Push failures: Shows the exact error from git

📁 Project Structure

gitcleancommit/
├── src/
│   ├── index.ts           # CLI entry point and command definitions
│   ├── prompt.ts          # Interactive prompt system with spell checking
│   ├── git-integration.ts # Git operations (add, commit, push)
│   ├── spellcheck.ts      # Spell checking engine and dictionary
│   └── banner.ts          # ASCII art banner display
├── dist/                  # Compiled JavaScript (generated)
├── package.json           # Package configuration
├── tsconfig.json          # TypeScript configuration
├── setup.js              # Post-install setup script
├── README.md             # This file
└── LICENSE               # MIT License

🐛 Troubleshooting

Common Issues and Solutions

"Not in a git repository"

# Initialize a git repository
git init

"No changes to commit"

# Check what has changed
gitclean status
# or
git status

"Push failed"

# Add a remote repository
git remote add origin https://github.com/username/repo.git

# Check current remotes
git remote -v

"Command not found: gitclean"

# Reinstall globally
npm install -g gitcleancommit

# Or use npx
npx gitcleancommit

Spell checker not working

# Check spell checker status
gitclean spellcheck --verbose

# Test with sample text
gitclean test

🤝 Contributing

We welcome contributions! Here's how to get started:

Fork the repository
Clone your fork: git clone https://github.com/yourusername/gitCleanCommit.git
Install dependencies: npm install
Create a feature branch: git checkout -b feature/amazing-feature
Make your changes
Build the project: npm run build
Test your changes: npm start
Commit using GitClean: npm start 😉
Push to your fork: git push origin feature/amazing-feature
Create a Pull Request

Development Setup

# Clone the repository
git clone https://github.com/thissudhir/gitCleanCommit.git
cd gitCleanCommit

# Install dependencies
npm install

# Build the TypeScript files
npm run build

# Run in development mode
npm run dev

# Test the CLI locally
npm start

📄 License

This project is licensed under the MIT License - see the LICENSE file for details.

🙏 Acknowledgments

Inspired by Conventional Commits specification
Built with Commander.js for CLI parsing
Uses Inquirer.js for interactive prompts
Spell checking powered by Typo.js
Beautiful terminal output with Chalk and Boxen

📞 Support

🚀 What's Next?

[ ] Configurable commit types
[ ] Custom spell check dictionaries
[ ] Multi-language support
[ ] Integration with issue trackers
[ ] Commit message templates
[ ] AI-powered commit message suggestions

Made with ❤️ by Abhishek

Happy committing! 🚀 May your git history always be clean and meaningful.

gitcleancommit