Location via proxy:   [ UP ]  
[Report a bug]   [Manage cookies]                
Skip to content

docs(init): rewrite commands init page #1461

New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Merged
merged 1 commit into from
May 28, 2025
Merged
Changes from all commits
Commits
File filter

Filter by extension

Filter by extension

Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
67 changes: 53 additions & 14 deletions docs/commands/init.md
Original file line number Diff line number Diff line change
@@ -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