CLI Interface

The git-cz CLI provides a command-line interface for creating semantic commits with interactive prompts and comprehensive configuration options.

Capabilities

Command-Line Execution

The CLI is available through two executable commands that provide identical functionality.

# Primary command
git-cz [options]

# Alternative command  
gitcz [options]

CLI Options:

• -h, --help - Show usage information
• -v, --version - Print version info and exit
• --disable-emoji - Don't add emoji to commit title
• --format - Custom formatting options for subject
• --non-interactive - Run git-cz in non-interactive mode
• --dry-run - Show what would be executed without running git commit
• --hook - Exit after writing commit message file (for git hooks)

Non-Interactive Mode Options

When using --non-interactive, these additional options are available:

• --type - Type of the commit, defaults to "chore"
• --subject - Message of the commit, defaults to "automated commit"
• --scope - Semantic commit scope
• --body - Extended description of the commit
• --breaking - Description of breaking changes, if any
• --issues - GitHub issues this commit closed, e.g "#123"
• --lerna - Lerna mono-repo packages this commit affects

Git Pass-Through Arguments

All additional arguments are passed through to the underlying git commit command.

# Pass-through examples
git-cz --amend              # Passes --amend to git commit
git-cz -a                   # Passes -a to git commit  
git-cz --allow-empty        # Passes --allow-empty to git commit

Usage Examples

Interactive Mode

# Basic interactive usage
git-cz

# Interactive with emoji disabled
git-cz --disable-emoji

# Interactive dry-run to see what would be executed
git-cz --dry-run

Non-Interactive Mode

# Minimal non-interactive commit
git-cz --non-interactive --type=feat --subject="add new feature"

# Complete non-interactive commit
git-cz --non-interactive \
  --type=feat \
  --scope=auth \
  --subject="implement OAuth integration" \
  --body="Added Google and GitHub OAuth providers with token refresh" \
  --breaking="OAuth configuration format changed" \
  --issues="#123 #124"

# Non-interactive with git options
git-cz --non-interactive --type=fix --subject="fix critical bug" --amend

Git Hook Integration

# For use in prepare-commit-msg hooks
git-cz --hook

This mode writes the commit message to .git/COMMIT_EDITMSG and exits without executing git commit, allowing git hooks to process the message.

Configuration with Custom Format

# Use custom subject formatting
git-cz --format="{type}{scope}: {subject} {emoji}"

Error Handling

The CLI includes several validation checks:

• No staged files: Exits with error if no files are staged (unless --allow-empty, -a, or --amend is used)
• Invalid git repository: Exits with error if not run in a git repository
• Configuration errors: Exits with error for invalid configuration files

Integration Patterns

Package.json Scripts

{
  "scripts": {
    "commit": "git-cz",
    "commit:auto": "git-cz --non-interactive --type=chore --subject=automated commit"
  }
}

Git Hooks

# .git/hooks/prepare-commit-msg
#!/bin/sh
exec < /dev/tty && git-cz --hook || true

CI/CD Integration

# Automated commits in CI
git add .
git-cz --non-interactive \
  --type=ci \
  --subject="update build artifacts" \
  --body="Automated commit from CI pipeline"