From 094e61631cb6e387665b17c835ba0a3e6c33321e Mon Sep 17 00:00:00 2001 From: Yu-Ting Hsiung Date: Wed, 28 May 2025 17:52:14 +0800 Subject: [PATCH] docs(init): rewrite commands init page --- docs/commands/init.md | 67 ++++++++++++++++++++++++++++++++++--------- 1 file changed, 53 insertions(+), 14 deletions(-) diff --git a/docs/commands/init.md b/docs/commands/init.md index a799c44810..4d92112d34 100644 --- a/docs/commands/init.md +++ b/docs/commands/init.md @@ -1,27 +1,66 @@ +The `cz init` command helps you set up Commitizen in your project by creating a configuration file with your preferred settings. + ## Usage ![cz init --help](../images/cli_help/cz_init___help.svg) -## Example - -To start using Commitizen, the recommended approach is to run +## Command ```sh cz init ``` +## Interactive Configuration + +When you run `cz init`, Commitizen will guide you through an interactive setup process: + ![init](../images/init.gif) -This command will ask you for information about the project and will -configure the selected file type (`pyproject.toml`, `.cz.toml`, etc.). +## Configuration File + +The initialization process will create a configuration file in your project root. + +Choose the configuration file format based on your project type: + +- Use `pyproject.toml` for Python projects +- Use `.cz.toml`, `.cz.yaml`, `.cz.json`, etc. for other projects. + +## Configuration Options + +During the initialization process, you'll be prompted to configure the following settings: + +1. **Convention Rules**: Select the commit message convention to follow (e.g., conventional commits) +2. **Version Provider**: Choose how to manage versioning in your project. Commitizen supports multiple version management systems: + - `commitizen`: Uses Commitizen's built-in version management system + - `npm`: Manages version in `package.json` for Node.js projects + - `cargo`: Manages version in `Cargo.toml` for Rust projects + - `composer`: Manages version in `composer.json` for PHP projects + - `pep621`: Uses `pyproject.toml` with PEP 621 standard + - `poetry`: Uses `pyproject.toml` with Poetry configuration + - `uv`: Uses `pyproject.toml` and `uv.lock` for Python projects + - `scm`: Reads version directly from git tags without modifying files +3. **Project Version**: The current version of your project will be detected automatically +4. **Tag Format**: The format used for version tags in your repository +5. **Version Type**: Choose between: + - `semver` or `semver2`: Semantic Versioning (MAJOR.MINOR.PATCH) + - `pep440`: Python Package Versioning +6. **Changelog Generation**: Configure whether to automatically generate changelog during version bumps +7. **Alpha Versioning**: Option to keep major version at 0 for alpha/beta software +8. **Pre-commit Hooks**: Set up Git pre-commit hooks for automated commit message validation + +## Example + +```sh +# Start the initialization process +cz init + +# Follow the interactive prompts to configure your project +``` + +## Next Steps -The `init` will help you with +After initialization, you can: -1. Choose a convention rules (`name`) -2. Choosing a version provider (`commitizen` or for example `Cargo.toml`) -3. Detecting your project's version -4. Detecting the tag format used -5. Choosing a version type (`semver` or `pep440`) -6. Whether to create the changelog automatically or not during bump -7. Whether you want to keep the major as zero while building alpha software. -8. Whether to setup pre-commit hooks. +1. Start using `cz commit` to create conventional commits +2. Use `cz bump` to manage versioning +3. Configure additional settings in your project's configuration file