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

1# Install globally (recommended)
2npm install -g gitcleancommit
3
4# Or use with npx (no installation)
5npx gitcleancommit
6
7# Or install as a dev dependency
8npm install --save-dev gitcleancommit

Basic Usage

1# Run the complete workflow (add → commit → push)
2gitclean
3
4# That's it! GitClean will handle everything else 🎉

📋 Commands

gitclean (default)

The main command that runs the complete git workflow:

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

1gitclean

gitclean commit

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

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

gitclean setup / gitclean install

Install GitClean as a git hook in your repository:

1gitclean setup
2# or
3gitclean 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:

1gitclean uninstall
2# or
3gitclean remove

gitclean status / gitclean s

Display the current git status:

1gitclean status
2# or
3gitclean s

gitclean spellcheck / gitclean spell

Test the spell checker with custom text:

1# Basic spell check
2gitclean spellcheck "your text here"
3
4# Verbose mode - shows dictionary stats
5gitclean spellcheck "your text" --verbose
6gitclean spellcheck "your text" -vr

gitclean test

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

1gitclean test

gitclean --version / gitclean -v

Show the current version:

1gitclean --version
2# or
3gitclean -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

1$ gitclean
2
3  GitClean Banner (ASCII Art)
4  Clean, conventional commits made easy
5
6🔍 Found changes to commit
7This will: git add . → git commit → git push
8
9🔤 Real-time spell checking enabled for text inputs!
10
11? Select the type of change you're committing: (Use arrow keys)
12❯ ADD          - Add new code or files
13  FIX          - A bug fix
14  UPDATE       - Updated a file or code
15  DOCS         - Documentation changes
16  TEST         - Adding tests
17  REMOVE       - Removing code or files

Commit with Scope

Add a scope to categorize your commits:

1? What is the scope of this change? (optional): auth
2? Write a short, imperative tense description: implement JWT token validation
3
4# Results in: ADD(auth): implement JWT token validation

Breaking Changes

Mark commits that introduce breaking changes:

1? Are there any breaking changes? Yes
2
3# Adds "BREAKING CHANGE:" to the commit body
4# Results in: ADD(auth)!: new authentication system

Issue References

Link commits to issues:

1? Add issue references: fixes #123, closes #456
2
3# Adds issue references to the commit body

Complete Example

1$ gitclean
2
3# After answering all prompts:
4
5┌─ Final Commit Message ──────────────────────────────────┐
6│ ➕ ADD(auth): implement JWT token validation            │
7│                                                         │
8│ Added secure token validation with refresh capability   │
9│                                                         │
10│ 💥 BREAKING CHANGE: implement JWT token validation      │
11│                                                         │
12│ fixes #123, closes #456                                 │
13└─────────────────────────────────────────────────────────┘
14
15? Ready to commit? Yes
16
17🚀 Starting GitClean workflow...
18
19✔ Files added: .
20✔ Commit created successfully!
21✔ Pushed to main successfully!
22
23✅ GitClean workflow completed successfully!
24📦 Changes pushed to main

🧪 Testing the Spell Checker

Interactive Testing

Test the spell checker with your own text:

1$ gitclean spellcheck "Fix fucntion that handls user authetication"
2
3🔍 Checking spelling...
4
5┌─ Spell Check Results ───────────────────────────────────┐
6│ ⚠️  Spelling issues found:                              │
7│                                                         │
8│ Original: Fix fucntion that handls user authetication   │
9│ Corrected: Fix function that handles user authentication│
10│                                                         │
11│ 📝 Issues found:                                        │
12│ • fucntion → function                                   │
13│ • handls → handles                                      │
14│ • authetication → authentication                        │
15└─────────────────────────────────────────────────────────┘

Verbose Mode

See detailed spell checker statistics:

1$ gitclean spellcheck --verbose
2
3┌─ Spell Checker Status ──────────────────────────────────┐
4│ 📊 Spell Checker Information                            │
5│                                                         │
6│ Initialized: ✅                                         │
7│ Dictionary: ✅ Loaded                                   │
8│ Technical words: 200+                                   │
9│ Typo correction rules: 100+                             │
10│                                                         │
11│ This spell checker is optimized for:                   │
12│ • Git commit messages                                   │
13│ • Programming terminology                               │
14│ • Common development terms                              │
15│ • Technical abbreviations                               │
16└─────────────────────────────────────────────────────────┘

Run Test Suite

Run the built-in test suite:

1$ gitclean test
2
3┌─ Spell Checker Test Suite ──────────────────────────────┐
4│ 🧪 Running Spell Checker Tests                          │
5│                                                         │
6│ Testing with common development-related text...         │
7└─────────────────────────────────────────────────────────┘
8
91. Testing: "Fix typo in fucntion name"
10   ❌ Found 1 issue(s)
11   🔧 Corrected: "Fix typo in function name"
12
132. Testing: "Add new componnet for user managment"
14   ❌ Found 2 issue(s)
15   🔧 Corrected: "Add new component for user management"
16
17# ... more test cases ...
18
19┌─ Test Results ──────────────────────────────────────────┐
20│ ✅ Test completed!                                      │
21│                                                         │
22│ Dictionary status: Active                               │
23│ Total technical terms: 200+                             │
24│ Total typo rules: 100+                                  │
25└─────────────────────────────────────────────────────────┘

🔧 Git Hook Integration

Automatic Setup

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

1# Install the hook
2gitclean setup
3
4# Now use git commit as usual
5git add .
6git commit  # GitClean will automatically run!

Manual Removal

Remove the git hook if needed:

1gitclean uninstall

How It Works

The git hook integration:

1. Creates a prepare-commit-msg hook in .git/hooks/
2. Runs GitClean automatically when you use git commit
3. Only activates for empty commit messages
4. 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:

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

Smart Change Detection

GitClean automatically detects if you have changes to commit:

1$ gitclean
2⚠️  No changes to commit
3Make some changes and run `gitclean` again
4
5💡 Try these commands:
6• gitclean spellcheck "your text" - Test spell checker
7• gitclean test - Run spell checker tests
8• 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"

1# Initialize a git repository
2git init

"No changes to commit"

1# Check what has changed
2gitclean status
3# or
4git status

"Push failed"

1# Add a remote repository
2git remote add origin https://github.com/username/repo.git
3
4# Check current remotes
5git remote -v

"Command not found: gitclean"

1# Reinstall globally
2npm install -g gitcleancommit
3
4# Or use npx
5npx gitcleancommit

Spell checker not working

1# Check spell checker status
2gitclean spellcheck --verbose
3
4# Test with sample text
5gitclean test

🤝 Contributing

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

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

Development Setup

1# Clone the repository
2git clone https://github.com/thissudhir/gitCleanCommit.git
3cd gitCleanCommit
4
5# Install dependencies
6npm install
7
8# Build the TypeScript files
9npm run build
10
11# Run in development mode
12npm run dev
13
14# Test the CLI locally
15npm 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

• 🐛 Report bugs
• 💡 Request features
• 📖 Documentation
• ⭐ Star on GitHub

🚀 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.