commit-emoji

A smart Git commit message enhancer that automatically suggests and adds appropriate emoji prefixes based on your code changes. Make your commit history more intuitive and fun!

Features

• Smart Analysis: Automatically analyzes your staged changes and suggests the most appropriate emoji
• Rich Rule Set: Comes with 30+ built-in emoji rules covering common scenarios
• File Pattern Matching: Recognizes file types and suggests context-aware emojis
• Keyword Detection: Analyzes commit diffs for keywords to determine intent
• CLI Tool: Easy-to-use command-line interface
• Customizable: Support for custom emoji rules
• TypeScript: Written in TypeScript with full type definitions

Installation

Global Installation (Recommended)

npm install -g commit-emoji

Local Installation

npm install --save-dev commit-emoji

Usage

Basic Usage

After staging your changes, simply run:

commit-emoji suggest

This will analyze your changes and suggest an appropriate emoji:

Analyzing staged changes...

Suggested emoji: ✨
Confidence: 85%

Example: ✨ your commit message

Format a Commit Message

commit-emoji format "add user authentication"

Output:

Formatted message:
✨ add user authentication

List All Available Emojis

commit-emoji list

This will display all available emoji rules with their descriptions and triggers.

Verbose Mode

Get detailed analysis of why an emoji was suggested:

commit-emoji suggest --verbose

Emoji Reference

Emoji	Description	Triggers
✨	New features	feature, add, new, implement, create
🐛	Bug fixes	fix, bug, resolve, issue, patch
📝	Documentation	doc, documentation, readme, *.md files
🎨	Code styling/refactoring	style, format, refactor, clean
⚡	Performance improvements	performance, optimize, faster, speed
🔥	Remove code/files	remove, delete, clean up, prune
🚀	Deployments	deploy, release, launch, publish
✅	Tests	test, testing, .test. files
🔒	Security fixes	security, secure, vulnerability, auth
⬆️	Upgrade dependencies	upgrade, update dependency, package.json
🔧	Configuration	config, settings, .config. files
🌐	Internationalization	i18n, translation, localization
💄	UI/Style files	ui, css, *.css files
🚧	Work in progress	wip, work in progress
💚	Fix CI build	ci, continuous integration, build
👷	CI/CD changes	ci, pipeline, .github/workflows/*
🔀	Merge branches	merge, branch
⏪	Revert changes	revert
🎉	Initial commit	initial, begin, start
💥	Breaking changes	breaking, breaking change
🩹	Simple fixes	simple fix, minor fix, typo
🗃️	Database changes	database, migration, schema
♻️	Refactoring	refactor
🔨	Development scripts	script, dev script

[See full list with commit-emoji list]

Integration

Git Hook Integration

Add to your .git/hooks/prepare-commit-msg:

#!/bin/bash
COMMIT_MSG_FILE=$1
COMMIT_SOURCE=$2

# Only run for new commits (not amend, merge, etc.)
if [ -z "$COMMIT_SOURCE" ]; then
  SUGGESTED=$(commit-emoji format "$(cat $COMMIT_MSG_FILE)" 2>/dev/null)
  if [ $? -eq 0 ]; then
    echo "$SUGGESTED" > $COMMIT_MSG_FILE
  fi
fi

Make it executable:

chmod +x .git/hooks/prepare-commit-msg

With Husky

Install husky:

npm install --save-dev husky
npx husky init

Add to .husky/prepare-commit-msg:

#!/bin/sh
COMMIT_MSG_FILE=$1

# Add emoji to commit message
SUGGESTED=$(commit-emoji format "$(cat $COMMIT_MSG_FILE)" 2>/dev/null)
if [ $? -eq 0 ]; then
  echo "$SUGGESTED" > $COMMIT_MSG_FILE
fi

NPM Scripts

Add to your package.json:

{
  "scripts": {
    "commit": "commit-emoji suggest && git commit",
    "commit:emoji": "commit-emoji suggest"
  }
}

API Usage

You can also use commit-emoji programmatically:

import { suggestEmoji, formatCommitMessage } from 'commit-emoji';

// Get suggestion
const result = await suggestEmoji();
console.log(result.emoji); // ✨
console.log(result.confidence); // 85
console.log(result.reason); // "Found keyword 'add' 3 time(s)"

// Format message
const formatted = formatCommitMessage('add new feature', result.emoji);
console.log(formatted); // "✨ add new feature"

Custom Rules

import { CommitAnalyzer, EmojiRule } from 'commit-emoji';

const customRules: EmojiRule[] = [
  {
    emoji: '🤖',
    keywords: ['ai', 'machine learning', 'ml'],
    description: 'AI/ML related changes'
  }
];

const analyzer = new CommitAnalyzer(customRules);
const result = analyzer.analyze(diffText, files);

Configuration

Create a .commit-emoji.json in your project root:

{
  "useConventionalCommits": true,
  "customRules": [
    {
      "emoji": "🤖",
      "keywords": ["ai", "ml", "neural"],
      "description": "AI/ML changes"
    }
  ]
}

Why Use Commit Emojis?

1. Visual Clarity: Quickly understand commit types at a glance
2. Better History: More engaging and easier to scan git history
3. Team Communication: Clearer intent communication across teams
4. Fun Factor: Make commits more enjoyable!

Examples

Before:

fix login validation
update documentation
add caching layer

After:

🐛 fix login validation
📝 update documentation
⚡ add caching layer

Contributing

Contributions are welcome! Here are some ways you can contribute:

• Add new emoji rules
• Improve analysis algorithm
• Add tests
• Improve documentation
• Report bugs
• Suggest features

Please read CONTRIBUTING.md for details on our code of conduct and the process for submitting pull requests.

Development

# Clone the repository
git clone https://github.com/yourusername/commit-emoji.git
cd commit-emoji

# Install dependencies
npm install

# Build
npm run build

# Run locally
npm link
commit-emoji suggest

# Run tests
npm test

License

MIT License - see LICENSE file for details

Acknowledgments

• Inspired by gitmoji
• Built with TypeScript
• Uses simple-git for Git operations

Support

• Report issues: GitHub Issues
• Star the project if you find it useful!
• Share with your team and friends

---

Made with ❤️ by the open source community