Interactive Git Commit Message CLI

Common errors

• czg: command not found

  cause `czg` is not installed globally or locally in a way that makes it available in the PATH, or `npx` is not being used to invoke it.
  fix Run `npm install -g czg` or `pnpm install -g czg` for global installation, or use `npx czg` to execute the local package without global installation. If using a package.json script, ensure `czg` is a local dependency.

• Error: Failed to load config from './.cz-config.js': Cannot find module 'cz-git'

  cause The configuration file for `czg` (often using `cz-git` internally) cannot resolve its dependencies or the path to `cz-git` itself. This can happen if `cz-git` is not installed or module resolution fails.
  fix Ensure `cz-git` is installed as a dependency (`npm install cz-git`) and that your configuration file's path is correct when specified with `--config`.

• Error: Configuration validation failed. Please check your .czrc or commitlint.config.js

  cause The loaded `czg` or `cz-git` configuration contains invalid properties, types, or violates schema rules.
  fix Review your configuration files against the `cz-git` documentation. Pay close attention to rules, prompts, and options. Use TypeScript with `defineConfig` or `UserConfig` for validation during development.

• API Key not found or invalid for OpenAI features. Please set OPENAI_API_KEY

  cause Attempted to use `czg ai` features without a valid OpenAI API key provided through environment variables or CLI options.
  fix Set the `OPENAI_API_KEY` environment variable (e.g., `export OPENAI_API_KEY=sk-...`) or provide it directly via the `--api-key` option (e.g., `czg ai --api-key=sk-...`).

Warnings

• breaking `czg` wraps `cz-git`, and major version upgrades of `cz-git` (e.g., from v1 to v2) can introduce breaking changes in configuration schemas or CLI options. Always consult the `cz-git` changelog for potential impacts on your `czg` setup.
  Fix: Review the changelogs for `cz-git` and `czg` before upgrading, particularly for major versions. Update configuration files (`.czrc`, `commitlint.config.js`, etc.) to match new specifications.
• gotcha Incorrect or malformed configuration files (e.g., `.czrc`, `.cz-git.cjs`, `commitlint.config.js`) are a common source of errors. czg relies heavily on these for customization, and syntax issues or invalid options can prevent the CLI from starting or behaving as expected.
  Fix: Always validate your configuration files against the official documentation and consider using TypeScript with `defineConfig` or `UserConfig` types for compile-time checks, especially for complex setups. Utilize the `$schema` property in JSON configuration files for IDE validation.
• gotcha To use `czg`'s OpenAI features for AI-generated commit messages, an `OPENAI_API_KEY` must be provided either via an environment variable or through the `--api-key` CLI option. Without it, AI features will fail or not be available.
  Fix: Ensure `OPENAI_API_KEY` is set in your environment variables, passed as a CLI argument (`--api-key=sk-XXXXX`), or configured in your `.czrc` file.
• gotcha Module resolution differences between CommonJS (CJS) and ES Modules (ESM) can cause issues when `czg` attempts to load configuration files. While `czg` explicitly supports `require('czg')` in `.js` config files, mixing module systems in your project's configuration can lead to 'module not found' errors.
  Fix: Ensure your configuration files use the appropriate module syntax (e.g., `module.exports` for CJS, `export default` for ESM/TypeScript) based on your project's `tsconfig.json` or `package.json` `type` field. Use `definePrompt` for CJS config files.

Install

• npm install czg npm
• yarn add czg yarn
• pnpm add czg pnpm

Imports

• definePrompt
  wrong:

  import { definePrompt } from 'czg'

  correct:

  const { definePrompt } = require('czg')

  Primarily used in CommonJS configuration files (e.g., .cz.js) to define the czg prompt configuration with type safety. This specific export is for CJS compatibility.
• UserConfig
  wrong:

  import { UserConfig } from 'czg'

  correct:

  import type { UserConfig } from 'czg'

  Type definition for czg (which re-exports cz-git's) user configuration. Essential for type-checking when defining configuration files in TypeScript projects.
• defineConfig
  wrong:

  const defineConfig = require('czg').defineConfig

  correct:

  import { defineConfig } from 'czg'

  Helper function for defining czg configuration objects (often in .cz-git.cjs or commitlint.config.js files) to gain type inference and validation. Typically used in ESM contexts or with TypeScript.

Quickstart

This quickstart demonstrates how to install and run the `czg` CLI tool, including how to invoke it directly, through an npm script, with a custom configuration file, and utilize its OpenAI integration for AI-generated commit messages.

{
  "scripts": {
    "commit": "czg"
  },
  "config": {
    "commitizen": {
      "path": "cz-git"
    }
  }
}

// To use it interactively:
npx czg

// Or if configured in package.json:
npm run commit

// Example with custom config file:
npx czg --config './.cz-config.js'

// Example using AI to generate commit message (requires OPENAI_API_KEY environment variable)
process.env.OPENAI_API_KEY ??= 'sk-your-openai-api-key'; // For local testing, ensure you set this
npx czg ai -M="gpt-4o-mini"

// Example .cz-config.js for programmatic configuration (using defineConfig from czg)
// /** @type {import('czg').UserConfig} */
// const config = defineConfig({
//   rules: {
//     'type-enum': [
//       2,
//       'always',
//       [
//         'feat', 'fix', 'docs', 'style', 'refactor', 'perf', 'test', 'build', 'ci', 'chore', 'revert', 'wip'
//       ]
//     ],
//     'scope-enum': [
//       2,
//       'always',
//       [
//         'core', 'components', 'utils', 'config', 'deps', 'release'
//       ]
//     ]
//   },
//   prompt: {
//     scopes: ['core', 'components', 'utils', 'config', 'deps', 'release']
//   }
// })
// module.exports = config;