@@ -48,81 +48,168 @@ This standardization makes your commit history more readable and meaningful, whi
4848- Display information about your commit rules (commands: schema, example, info)
4949- Create your own set of rules and publish them to pip. Read more on [ Customization] ( ./customization.md )
5050
51- ## Requirements
51+ ## Getting Started
5252
53- [ Python ] ( https://www.python.org/downloads/ ) ` 3.9+ `
53+ ### Requirements
5454
55- [ Git ] [ gitscm ] ` 1.8.5.2+ `
55+ Before installing Commitizen, ensure you have:
5656
57- ## Installation
57+ - [ Python] ( https://www.python.org/downloads/ ) ` 3.9+ `
58+ - [ Git] [ gitscm ] ` 1.8.5.2+ `
5859
59- Install commitizen in your system using ` pipx ` (Recommended, < https://pypa.github.io/pipx/installation/ > ):
60+ ### Installation
61+ 62+ #### Global Installation (Recommended)
63+ 64+ The recommended way to install Commitizen is using ` pipx ` , which ensures a clean, isolated installation:
6065
6166``` bash
67+ # Install pipx if you haven't already
6268pipx ensurepath
69+ 70+ # Install Commitizen
6371pipx install commitizen
72+ 73+ # Keep it updated
6474pipx upgrade commitizen
6575```
6676
67- Install commitizen using ` pip ` with the ` --user ` flag :
77+ If you're on macOS, you can also install Commitizen using Homebrew :
6878
6979``` bash
70- pip install --user -U commitizen
80+ brew install commitizen
7181```
7282
73- ###Python project
83+ #### Project-Specific Installation
7484
75- You can add it to your local project using one of the following methods.
85+ You can add Commitizen to your Python project using any of these package managers:
7686
77- With ` pip ` :
87+ ** Using pip: **
7888
7989``` bash
8090pip install -U commitizen
8191```
8292
83- With ` conda ` :
93+ ** Using conda: **
8494
8595``` bash
8696conda install -c conda-forge commitizen
8797```
8898
89- With Poetry >= 1.2.0:
99+ ** Using Poetry: **
90100
91101``` bash
102+ # For Poetry >= 1.2.0
92103poetry add commitizen --group dev
104+ 105+ # For Poetry < 1.2.0
106+ poetry add commitizen --dev
93107```
94108
95- With Poetry < 1.2.0:
109+ ### Basic Commands
96110
97- ``` bash
98- poetry add commitizen --dev
111+ #### Initialize Commitizen
112+ 113+ To get started, you'll need to set up your configuration. You have two options:
114+ 115+ 1 . Use the interactive setup:
116+ ``` sh
117+ cz init
99118```
100119
101- ### macOS
120+ 2 . Manually create a configuration file (` .cz.toml ` or ` cz.toml ` ):
121+ ``` toml
122+ [tool .commitizen ]
123+ version = " 0.1.0"
124+ update_changelog_on_bump = true
125+ ```
102126
103- via [ homebrew ] ( https://formulae.brew.sh/formula/commitizen ) :
127+ #### Create Commits
104128
105- ``` bash
106- brew install commitizen
129+ Create standardized commits using:
130+ ``` sh
131+ cz commit
132+ # or use the shortcut
133+ cz c
107134```
108135
109- ## Usage
136+ To sign off your commits:
137+ ``` sh
138+ cz commit -- --signoff
139+ # or use the shortcut
140+ cz commit -- -s
141+ ```
110142
111- Most of the time, this is the only command you'll run:
143+ For more commit options, run ` cz commit --help ` .
112144
145+ #### Version Management
146+ 147+ The most common command you'll use is:
113148``` sh
114149cz bump
115150```
116151
117- On top of that, you can use commitizen to assist you with the creation of commits:
152+ This command:
153+ - Bumps your project's version
154+ - Creates a git tag
155+ - Updates the changelog (if ` update_changelog_on_bump ` is enabled)
156+ - Updates version files
157+ 158+ You can customize:
159+ - [ Version files] ( ./commands/bump.md#version_files )
160+ - [ Version scheme] ( ./commands/bump.md#version_scheme )
161+ - [ Version provider] ( ./config.md#version-providers )
162+ 163+ For all available options, see the [ bump command documentation] ( ./commands/bump.md ) .
164+ 165+ ### Advanced Usage
166+ 167+ #### Get Project Version
118168
169+ To get your project's version (instead of Commitizen's version):
119170``` sh
120- cz commit
171+ cz version -p
172+ ```
173+ 174+ This is particularly useful for automation. For example, to preview changelog changes for Slack:
175+ ``` sh
176+ cz changelog --dry-run " $( cz version -p) "
177+ ```
178+ 179+ #### Pre-commit Integration
180+ 181+ Commitizen can automatically validate your commit messages using pre-commit hooks.
182+ 183+ 1 . Add to your ` .pre-commit-config.yaml ` :
184+ ``` yaml
185+ ---
186+ repos :
187+ - repo : https://github.com/commitizen-tools/commitizen
188+ rev : master # Replace with latest tag
189+ hooks :
190+ - id : commitizen
191+ - id : commitizen-branch
192+ stages : [pre-push]
193+ ` ` `
194+
195+ 2. Install the hooks:
196+ ` ` ` sh
197+ pre-commit install --hook-type commit-msg --hook-type pre-push
121198```
122199
123- Read more in the section [ Getting Started] ( ./getting_started.md ) .
200+ | Hook | Recommended Stage |
201+ | ----------------- | ----------------- |
202+ | commitizen | commit-msg |
203+ | commitizen-branch | pre-push |
204+ 205+ > ** Note** : Replace ` master ` with the [ latest tag] ( https://github.com/commitizen-tools/commitizen/tags ) to avoid warnings. You can automatically update this with:
206+ > ``` sh
207+ > pre-commit autoupdate
208+ > ` ` `
124209
125- ### Help
210+ For more details about commit validation, see the [check command documentation](commands/check.md).
211+
212+ # # Usage
126213
127214< ! -- Please manually update the following section after changing ` ` command output. -->
128215
0 commit comments