Commitizard 🧙‍♂️

Commitizard is a TypeScript-based Command Line Interface (CLI) wizard application designed to help developers write better commit messages. It supports conventional commits and red-green-refactor commit strategies. The project is fully configurable through the .commitizard.json file.

Table of Contents

• Features
• Installation
• Usage
• Commands
  • Wizard (default)
    • Options
    • Overviews
  • Config
    • Options
  • Hook
    • Options
• Configuration
• Examples
• Advanced Usages
  • Customizing Prompts
  • Custom Commit Message Templates for Red-Green-Refactor Strategy
  • Bypassing Git Hooks with the environment variable
    • Unix based systems
    • Windows
• Contributing
• License

🌟 Features

• Wizard-style commit message generation
• Supports conventional and red-green-refactor (TDD) commit strategies
• Fully configurable through .commitizard.json
• Git hook management
• Application configuration management

💻 Installation

Commitizard is designed for local use as part of a development workflow. Install it locally in your project:

npm install --save-dev commitizard

Or install it globally to use it from any git directory:

npm install -g commitizard

🚀 Usage

Local Installation

When installed locally, it's recommended to create a script in your package.json file. This allows you to pass any desired options and helps you avoid potential side effects related to hooks. Adding a Commitizard Script

To add a script to your package.json file, add the following line to the scripts section:

"commitizard": "commitizard -s conventional -D"

Replace -s conventional and -D options with any Commitizard wizard options you want to use.

Global Installation

For global installations, you can create a Git alias to easily run Commitizard from any git directory:

git config --global alias.cw "commitizard"

With this alias, you can use git cw to run Commitizard.

General Usage

commitizard [command] [options]

For more detailed information on available commands and options, run:

commitizard --help

🛠️ Commands

Commitizard provides the following commands:

1. wizard: A CLI tool for generating commit messages.
2. config: Manage the application configuration.
3. hook: Manage the application hooks.

Wizard (default)

The Wizard command is responsible for generating commit messages based on user input and the selected commit strategy. If the -s, --strategy option is not provided, Commitizard will prompt the user to choose between the conventional and red-green-refactor commit strategies before proceeding with the commit message generation. This interactive confirmation ensures that the appropriate commit message format is used based on the user's preference or project requirements.

Options

• -p, --path <path>: Path to the configuration file
• -D, --display-staged-files: Display staged files before prompting for commit message
• -S, --select-files: Prompt user to select files to stage before prompting for commit message
• -s, --strategy: Commit message strategy to use
• -e, --with-emoji: Use a relevant emoji as a prefix for the commit message type
• --from-hook: Indicates that the command was called from a git hook

Overviews

1. commitizard --display-staged-files --strategy red-green-refactor

2. commitizard --select-files

3. commitizard --strategy conventional --with-emoji

4. commitizard --display-staged-files

5. Using hooks: git commit

Config

The Config command is responsible for managing the application configuration.

Options

• -p, --path <path>: Path to the configuration file
• -i, --install: Install the configuration file
• -e, --with-emoji: Use the emoji configuration file
• -b, --backup: Backup the configuration file
• -r, --restore: Restore the configuration file
• -d, --delete: Delete the configuration file

Hook

The Hook command is responsible for managing the application hooks.

Options

• -i, --install: Install the hooks
• -u, --uninstall: Uninstall the hooks

🔧 Configuration

Commitizard is fully configurable via a JSON file. It can be generated into your project folder using the commitizard config -i or commitizard config --install command.

The configuration file includes settings for both conventional and red-green-refactor commit message patterns. Here is an example of the available configuration options:

1. Conventional Commits

• types (array): An array of commit types, with each item containing a value and label.
  • value represents the type of the commit (e.g. feat, fix, docs).
  • label is the text that will be displayed in the interactive prompt to describe the type of the commit.
• scopes (array): An array of commit scopes, with each item containing a value and label.
  • value represents the scope of the commit (e.g. core, ui, docs)
  • label is the text that will be displayed in the interactive prompt to describe the scope of the commit.

2. Red-Green-Refactor Commits

• types (array): An array of commit types, with each item containing a value, label, and patterns.
  • value represents the type of the commit (e.g. RED, GREEN, REFACTOR).
  • label is the text that will be displayed in the interactive prompt to describe the type of the commit.
  • patterns is an array of regular expressions or strings that will be used to match against the commit message when generating a commit. If a match is found, the commit type will be automatically set to the corresponding value.

The configuration file can be edited to add, remove, or modify the available options for commit types and scopes. This allows you to fully customize the prompts and messages generated by Commitizard to match your team's specific needs.

📚 Examples

Here's an example configuration file:

Click to show

{
  "version": "0.0.1",
  "settings": {
    "maxViewFilesToShow": 5,
    "excludePaths": [
      "package-lock.json",
      "yarn.lock",
      "pnpm-lock.yaml",
      "**/yarn.lock",
      "**/pnpm-lock.yaml",
      "**/package-lock.json"
    ]
  },
  "conventional": {
    "commitOptions": {
      "template": {
        "type": "{{type}}",
        "scope": "({{scope}})",
        "subject": ": {{subject}}",
        "body": "\n\n{{body}}",
        "footer": "\n\n{{footer}}",
        "breaking": "\n\nBREAKING CHANGE:\n {{breaking}}",
        "refs": "\n\nRefs: {{refs}}"
      },
      "templateOrder": [
        "type",
        "scope",
        "subject",
        "body",
        "breaking",
        "footer",
        "refs"
      ]
    },
    "cliOptions": {
      "scopes": [
        {
          "value": "core",
          "label": "Core"
        },
        {
          "value": "common",
          "label": "Common"
        },
        {
          "value": "domain",
          "label": "Domain"
        },
        {
          "value": "infra",
          "label": "Infra"
        },
        {
          "value": "business",
          "label": "Business"
        }
      ],
      "types": [
        {
          "value": "feat",
          "label": "feat: A new feature"
        },
        {
          "value": "fix",
          "label": "fix: A bug fix"
        },
        {
          "value": "docs",
          "label": "docs: Documentation only changes"
        },
        {
          "value": "style",
          "label": "style: Changes that do not affect the meaning of the code"
        },
        {
          "value": "refactor",
          "label": "refactor: A code change that neither fixes a bug nor adds a feature"
        },
        {
          "value": "perf",
          "label": "perf: A code change that improves performance"
        },
        {
          "value": "test",
          "label": "test: Adding missing tests or correcting existing tests"
        },
        {
          "value": "ci",
          "label": "ci: Changes to our CI configuration files and scripts"
        },
        {
          "value": "chore",
          "label": "chore: Changes to the build process or auxiliary tools and libraries"
        }
      ]
    }
  },
  "redGreenRefactor": {
    "commitOptions": {
      "template": {
        "type": "[{{type}}]: ",
        "subject": "{{subject}}",
        "body": "\n\n{{body}}"
      },
      "templateOrder": ["type", "subject", "body"]
    },
    "cliOptions": {
      "types": [
        {
          "value": "RED",
          "label": "RED: Write a test that fails",
          "patterns": [
            "Add failing test for {{feature}}",
            "Write failing test for {{feature}}",
            "Create failing test for {{feature}}",
            "Implement failing test for {{feature}}",
            "Introduce failing test for {{feature}}",
            "Start failing test for {{feature}}",
            "Begin failing test for {{feature}}",
            "Initiate failing test for {{feature}}",
            "Setup failing test for {{feature}}"
          ]
        },
        {
          "value": "GREEN",
          "label": "GREEN: Make the test pass",
          "patterns": [
            "Make test pass for {{feature}}",
            "Fix failing test for {{feature}}",
            "Implement solution for {{feature}}",
            "Add code to pass test for {{feature}}",
            "Introduce passing test for {{feature}}",
            "Start passing test for {{feature}}",
            "Begin passing test for {{feature}}",
            "Initiate passing test for {{feature}}",
            "Setup passing test for {{feature}}"
          ]
        },
        {
          "value": "REFACTOR",
          "label": "REFACTOR: Refactor the code without changing functionality",
          "patterns": [
            "Refactor {{feature}} to improve {{performance/maintainability/readability/usability}}",
            "Restructure {{feature}} to {{simplify/consolidate/clarify}}",
            "Extract {{feature}} to {{separate file/module}}",
            "Inline {{feature}}",
            "Rename {{feature}} to {{new name}}",
            "Move {{feature}} to {{new location}}",
            "Reorganize {{feature}} to {{streamline/improve}}",
            "Simplify {{feature}} by {{removing unnecessary code/logic}}",
            "Optimize {{feature}} by {{reducing complexity/improving efficiency}}",
            "Improve {{feature}} by {{cleaning up/rewriting}} code for {{clarity/consistency}}"
          ]
        }
      ]
    }
  }
}

⚙️ Advanced Usages

1. Customizing Prompts for Conventional Strategy

You can customize the interactive prompts displayed by Commitizard by modifying the label property of the types and scopes objects in your .commitizard.json configuration file. This allows you to provide more descriptive or project-specific information to guide users when creating commit messages.

For example, if your project has a specific set of modules, you can define custom scope labels like this:

"scopes": [
  {
    "value": "module-a",
    "label": "Module A (user management)"
  },
  {
    "value": "module-b",
    "label": "Module B (payment processing)"
  }
]

These custom labels will be displayed in the interactive prompts, making it easier for users to select the appropriate scope for their commit.

2. Custom Commit Message Templates for Red-Green-Refactor Strategy

You can create custom commit message templates for the Red-Green-Refactor strategy to fit your project's specific requirements. To do this, modify the patterns array for each commit type (RED, GREEN, and REFACTOR) in the redGreenRefactor.cliOptions.types section of your .commitizard.json configuration file.

For example, to add a custom pattern for the RED type, your configuration file could include the following entry:

{
  "value": "RED",
  "label": "RED: Write a test that fails",
  "patterns": [
    ...,
      "New custom pattern for RED commits {{feature}}"  ]
}

Replace New custom pattern for RED commits {{feature}} with your desired pattern. The {{feature}} placeholder will be replaced by the user input when generating the commit message.

3. Bypassing Hooks with the Environment Variable

In some cases, you might want to bypass the git hooks managed by Commitizard. This can be done by setting the COMMITIZARD_BYPASS environment variable to true before executing the git command. Here, you can find more information about the technical choice

Unix-based Systems

On Unix-based systems (Linux, macOS), use the following command to bypass the prepare-commit-msg hook:

COMMITIZARD_BYPASS=true git commit -m "Your commit message"

or

COMMITIZARD_BYPASS=true git rebase -i HEAD~3

Windows

On Windows, you can bypass the prepare-commit-msg hook using the following command:

set COMMITIZARD_BYPASS=true && git commit -m "Your commit message"

or

set COMMITIZARD_BYPASS=true && git rebase -i HEAD~3

By setting the COMMITIZARD_BYPASS environment variable, you can control when the hooks should be executed, giving more flexibility during development.

🤝 Contributing

Please feel free to submit issues and pull requests for bug fixes, features, or improvements. We appreciate your contribution to the project!

⚖️ License

Commitizard is MIT licensed.