Skip to content

README.md

Latest commit

 

History

History
207 lines (144 loc) · 5.52 KB

README.md

File metadata and controls

207 lines (144 loc) · 5.52 KB
Raw

CLI Conventional Commit

A beautiful interactive CLI tool for creating conventional commits with gitmoji support. Built with Bun and designed to make your commit messages consistent and meaningful.

Bun

Features

  • 🎯 Interactive prompts for conventional commit types
  • 🎨 Built-in gitmoji support with visual previews
  • 📦 Workspace-aware scope detection (from VS Code workspace files)
  • ✨ Beautiful terminal UI with colors and spinners
  • 🚀 Fast execution with Bun
  • 🔍 Smart package detection for monorepos

Installation

Pre-built Binaries

Download the latest release for your platform:

  • Linux x64: ccommit-linux-x64
  • Linux ARM64: ccommit-linux-arm64
  • Windows x64: ccommit-windows-x64.exe
  • macOS x64: ccommit-macos-x64
  • macOS ARM64: ccommit-macos-arm64 (Apple Silicon)
# Linux/macOS - make executable and move to PATH
chmod +x ccommit-*
sudo mv ccommit-* /usr/local/bin/ccommit

# Windows - add to PATH or rename to ccommit.exe

From NPM

npm install -g cli-conventional-commit

From Source

Requires Bun to be installed:

git clone https://gitlab.com/your-username/cli-conventional-commit.git
cd cli-conventional-commit
bun install
bun run build

Usage

Make sure you have staged changes in git, then run:

ccommit

The CLI will guide you through:

  1. Type Selection: Choose from conventional commit types (feat, fix, docs, etc.)
  2. Scope Selection: Pick from detected workspace packages or enter custom scope
  3. Gitmoji Selection: Add an emoji that represents your change
  4. Description: Write a short, clear description
  5. Body (optional): Add detailed explanation
  6. Breaking Changes (optional): Document any breaking changes

Example Output

feat(auth): ✨ add OAuth2 integration

- Implement Google OAuth2 provider
- Add user session management
- Update login UI components

BREAKING CHANGE: Auth configuration format has changed

Conventional Commit Types

  • feat: A new feature
  • fix: A bug fix
  • docs: Documentation only changes
  • style: Changes that do not affect the meaning of the code
  • refactor: A code change that neither fixes a bug nor adds a feature
  • perf: A code change that improves performance
  • test: Adding missing tests or correcting existing tests
  • build: Changes that affect the build system or external dependencies
  • ci: Changes to CI configuration files and scripts
  • chore: Other changes that don't modify src or test files
  • revert: Reverts a previous commit

Workspace Integration

The CLI looks for any *.code-workspace file in:

  • .vscode/ (current directory)
  • ../../.vscode/ (parent directories)

to detect scopes from your VS Code workspace configuration:

{
  "folders": [
    { "name": "frontend", "path": "./packages/frontend" },
    { "name": "backend", "path": "./packages/backend" },
    { "name": "shared", "path": "./packages/shared" }
  ]
}

These folder names will appear as scope options during commit creation.

Development

Prerequisites

  • Bun runtime
  • Git repository with staged changes

Local Development

# Install dependencies
bun install

# Run directly
bun run index.ts

# Build for current platform
bun run build

# Build for all platforms
bun run build:all

# Lint code
bun run lint

# Format code
bun run fmt

Building

The project uses Bun's compile feature to create standalone executables:

# Build for specific targets
bun build --compile --target=bun-linux-x64 ./index.ts --outfile ccommit-linux-x64
bun build --compile --target=bun-windows-x64 ./index.ts --outfile ccommit-windows-x64.exe
bun build --compile --target=bun-darwin-x64 ./index.ts --outfile ccommit-macos-x64
bun build --compile --target=bun-darwin-arm64 ./index.ts --outfile ccommit-macos-arm64

CI/CD

This project uses GitLab CI/CD with semantic-release for automated publishing:

  • Linting: Code quality checks on all branches
  • Building: Multi-platform binary compilation
  • Testing: Automated testing pipeline
  • Releasing: Semantic versioning and NPM publishing
  • Assets: Binary uploads to GitLab releases

Pipeline Stages

  1. Test: Lint and format validation
  2. Build: Compile binaries for all supported platforms
  3. Release: Semantic release with version bumping and changelog generation

Contributing

  1. Fork the repository
  2. Create a feature branch: git checkout -b feature/amazing-feature
  3. Make your changes and test locally
  4. Use this tool to create your commit: bun run index.ts
  5. Push to your branch: git push origin feature/amazing-feature
  6. Open a merge request

Commit Message Format

This project follows the Conventional Commits specification:

<type>[optional scope]: <description>

[optional body]

[optional footer(s)]

License

MIT License - see the LICENSE file for details.

Changelog

See CHANGELOG.md for a detailed history of changes.

Support