Skip to content

commit.md

Latest commit

 

History

History
103 lines (69 loc) · 3.85 KB

commit.md

File metadata and controls

103 lines (69 loc) · 3.85 KB

Usage

cz commit --help

Overview

Using Commitizen cli

The commit command provides an interactive way to create structured commits. Use either:

  • cz commit
  • cz c (shortcut)

By default, Commitizen uses conventional commits, but you can customize the commit rules to match your project's needs. See the customization guide for details.

Basic Usage

Interactive Commit Creation

Simply run cz commit in your terminal to start the interactive commit creation process. The command will guide you through creating a properly formatted commit message according to your configured rules.

Writing Messages to File

You can save the generated commit message to a file using:

cz commit --write-message-to-file COMMIT_MSG_FILE

This can be combined with --dry-run to only write the message without creating a commit. This is particularly useful for automatically preparing commit messages.

Multiline Input Support

Commitizen now supports enhanced multiline input for commit messages, making it easier to create detailed, well-structured commits.

How It Works

When prompted for input during cz commit, you can now use multiline input with smart behavior:

For Optional Fields (scope, body, footer)

  • Enter on empty line → Skips the field
  • Enter after typing content → Adds a new line for multiline input
  • Alt+Enter → Finishes and submits the input

For Required Fields (subject)

  • Enter on empty line → Shows error message with options: 
    ⚠ This field is required. Please enter some content or press Ctrl+C to abort.
>
  • Enter after typing content → Adds a new line for multiline input
  • Alt+Enter → Finishes and submits the input
  • Ctrl+C → Aborts the commit session

Example Usage

cz commit

During the interactive process:

  1. Commit Type: Select from the list (e.g., feat, fix, docs)
  2. Scope (optional): Press Enter to skip, or type scope and use Enter for multiline
  3. Subject (required): Must enter content, can use Enter for multiline, Alt+Enter to finish
  4. Body (optional): Press Enter to skip, or add detailed description with multiline support
  5. Breaking Change: Yes/No confirmation
  6. Footer (optional): Press Enter to skip, or add references/notes with multiline support

Advanced Features

Git Command Options

You can pass any git commit options using the -- syntax:

cz commit <commitizen-args> -- <git-cli-args>

# Examples:
cz c --dry-run -- -a -S  # Stage all changes and sign the commit
cz c -a -- -n            # Stage all changes and skip the pre-commit and commit-msg hooks

!!! warning The --signoff option (or -s) is now recommended being used with the new syntax: cz commit -- -s. The old syntax cz commit --signoff is deprecated and will be removed in v5.

Retry

  • Use cz commit --retry to reuse the last commit message after a failed commit attempt
  • Set retry_after_failure: true in your configuration to automatically retry
  • Use cz commit --no-retry to force a new commit message prompt

Message Length Control

Control the length of your commit messages using the -l or --message-length-limit option:

cz commit -l 72  # Limits message length to 72 characters

!!! note The length limit only applies to the first line of the commit message. For conventional commits, this means the limit applies from the type of change through the subject. The body and footer are not counted.

Technical Notes

For platform compatibility, the commit command disables ANSI escaping in its output. This means pre-commit hooks coloring will be deactivated as discussed in commitizen-tools/commitizen#417.