commitizen

Command line utility to standardize git commit messages, golang version. Forked from commitizen-go.

Fixes some issues of commitizen-go and supports more new features.

Features

• Multi-template support.
• More powerful and flexible template.
• Support more options of git commit.
• Use huh instead of survey (survey is no longer maintained).

Getting Started

Command line utility to standardize git commit messages.
Usage:
commitizen
Available Commands:
init Install this tool to git-core as git-cz.
version Print the CLI version information. help Help about any command
Git Commit flags:
-a, --all
commit all changed files.
--amend
amend previous commit
--author string
override author for commit
--date string
override date for commit
--git-flag strings
git flags, e.g. --git-flag="--branch"
-n, --no-verify
bypass pre-commit and commit-msg hooks. -q, --quiet
suppress summary after successful commit
-s, --signoff
add a Signed-off-by trailer.
-v, --verbose
show diff in commit message template
Commitizen flags:
-d, --default
use the default template, '--default' has a higher priority than '--template'.
--dry-run
do not create a commit, but show the message and list of paths
that are to be committed.
-t, --template string
template name to use when multiple templates exist.
Use "commitizen [command] --help" for more information about a command.

To use more Git flags, you can use the '--git-flag' flag. Please do not conflict with other Git commit flags.

Commit with commitizen:

$ git cz

Installation

Homebrew

$ brew tap shipengqi/casks
$ brew install commitizen
$ sudo commitizen init

Scoop (Windows)

$ scoop bucket add czbucket https://github.com/shipengqi/scoop-bucket.git
$ scoop install commitizen
$ commitizen.exe init

From the Binary Releases

Download the pre-compiled binaries from the releases page and copy them to the desired location.

Then install this tool to git-core as git-cz:

$ commitizen init

Go Install

You must have a working Go environment:

$ go install github.com/shipengqi/commitizen@latest
$ commitizen init

From Source

You must have a working Go environment:

$ git clone https://github.com/shipengqi/commitizen.git
$ cd commitizen
$ make && ./_output/$(GOOS)/$(GOARCH)/bin/commitizen init

Configuration

You can set configuration file that .czrc at repository root, home directory, or the $XDG_CONFIG_HOME/commitizen directory.

commitizen uses the following precedence order. Each item takes precedence over the item below it:

• per-project config file (/path/to/my/project/.czrc)
• per-user config file (~/.czrc)
• $XDG_CONFIG_HOME config file ($XDG_CONFIG_HOME/commitizen/.czrc)

The format is the same as the following:

name: defaultdefault: truegroups:
- name: hasbreakingdepends_on:
and_conditions:
- parameter_name: page2.isbreakingvalue_equals: true
- name: nobreakingdepends_on:
and_conditions:
- parameter_name: page2.isbreakingvalue_equals: falseitems:
- name: typegroup: page1label: "Select the type of change that you're committing:"type: listoptions:
- value: featkey: "feat: A new feature"
- value: fixkey: "fix: A bug fix"
- value: docskey: "docs: Documentation only changes"
- value: testkey: "test: Adding missing or correcting existing tests"
- value: chorekey: "chore: Changes to the build process or auxiliary tools and libraries such as documentation generation"
- value: stylekey: "style: Changes that do not affect the meaning of the code (white-space, formatting, missing semi-colons, etc)"
- value: refactorkey: "refactor: A code change that neither fixes a bug nor adds a feature"
- value: perfkey: "perf: A code change that improves performance"
- value: revertkey: "revert: Reverts a previous commit"
- name: scopegroup: page2label: "Scope. What is the scope of this change? (class or file name):"type: stringtrim: true
- name: subjectgroup: page2label: "Subject. Write a short and imperative summary of the code change (lower case and no period):"type: stringrequired: truetrim: true
- name: isbreakinggroup: page2label: "Are there any breaking changes?"type: boolean
- name: hasbreakingbodygroup: hasbreakinglabel: "A BREAKING CHANGE commit requires a body. Provide additional contextual information about the code changes:"type: textrequired: true
- name: nobreakingbodygroup: nobreakinglabel: "Body. Provide additional contextual information about the code changes:"type: text
- name: footergroup: page3label: "Footer. Information about Breaking Changes and reference issues that this commit closes:"type: textformat: "{{.type}}{{with .scope}}({{.}}){{end}}: {{.subject}}{{with .hasbreakingbody}}\n\n{{.}}{{end}}{{with .nobreakingbody}}\n\n{{.}}{{end}}{{with .footer}}\n\n{{.}}{{end}}"

Default

Optional. If true, the template will be used as the default template, note that there can only be one default template.

Format

Commit message format:

format: "{{.type}}{{with .scope}}({{.}}){{end}}: {{.subject}}{{with .body}}\n\n{{.}}{{end}}{{with .footer}}\n\n{{.}}{{end}}"

Items

Common Item Properties

Property	Required	Default Value	Description
name	yes	-	Unique identifier for the item.
label	yes	-	This will be used as the label for the input field in the UI.
type	yes	-	The type of item. Determines which UI widget is shown. See the Item Types section to see all the different options.
group	no	-	The name of the group this item belongs to. Separates items into groups (you can think of groups as pages).
description	no	-	A short description of the item for user guidance. This will be displayed along with the input field.

Item Types

• string
• text
• integer
• boolean
• secret
• list
• multi_list

string

string are single line text parameters.

Properties:

Property	Required	Default Value	Description
required	no	false	Whether a string value is required or not.
fqdn	no	false	Add a preset FQDN regex to validate string.
ip	no	false	Add a preset IPv4/IPv6 regex to validate string.
trim	no	false	If true, will remove the leading and trailing blank characters before submit.
default_value	no	-	The default value for this item.
regex	no	-	A regex used to validate the string.
min_length	no	-	The minimum length of the string. If the value is not required and no value has been given, this is ignored.
max_length	no	-	The maximum length of the string.

text

Properties:

Property	Required	Default Value	Description
required	no	false	Whether the text is required or not.
height	no	5	The height of the text.
default_value	no	-	The default value for this item.
regex	no	-	A regex used to validate the text.
min_length	no	-	The minimum length of the text. If the value is not required and no value has been given, this is ignored.
max_length	no	-	The maximum length of the text.

integer

integer is a number.

Properties:

Property	Required	Default Value	Description
required	no	false	Whether the integer is required or not.
default_value	no	-	The default value for this item.
min	no	-	The minimum value allowed.
max	no	-	The maximum value allowed.

boolean

boolean are true or false values.

Properties:

Property	Required	Default Value	Description
default_value	no	-	The default value for this item.

secret

secret is used for sensitive data that should not be echoed in the UI, for example, passwords.

Properties:

Property	Required	Default Value	Description
required	no	false	Whether the secret is required or not.
trim	no	false	If true, will remove the leading and trailing blank characters before submit.
default_value	no	-	The default value for this item.
regex	no	-	A regex used to validate the secret.
min_length	no	-	The minimum length of the secret. If the value is not required and no value has been given, this is ignored.
max_length	no	-	The maximum length of the secret.

list

list is predefined lists of values that can be picked by the user.

Properties:

Property	Required	Default Value	Description
required	no	false	Whether a string value is required or not.
default_value	no	-	The default value for this item.
options	yes	-	The list of options to choose from.
height	no	-	The height of the list. If the number of options exceeds the height, the list will become scrollable.

multi_list

Similar to list, but with multiple selection.

Properties:

Property	Required	Default Value	Description
required	no	false	Whether a string value is required or not.
default_value	no	-	A list of default selection values.
options	yes	-	The list of options to choose from.
limit	no	false	The limit of the multiple selection list.
height	no	-	The height of the list. If the number of options exceeds the height, the list will become scrollable.

list/multi_list Options

Properties:

Property	Required	Description
key	yes	The message shown in the UI.
value	yes	Unique identifier for the value.

Groups (Optional)

Group Properties:

Property	Required	Default Value	Description
name	yes	-	Unique identifier for the property.
depends_on	no	-	If this group should only be shown when a specific condition is met on another property.

DependsOn Properties:

Property	Required	Default Value	Description
or_conditions	no	[]	The list of conditions in which at least one must be satisfied for the property to be shown.
and_conditions	no	[]	The list of conditions in which all must be satisfied for the property to be shown.

DependsOn Conditions:

• ValueEqualsCondition
• ValueNotEqualsCondition
• ValueContainsCondition
• ValueNotContainsCondition
• ValueEmptyCondition

ValueEqualsCondition

Properties:

Property	Required	Default Value	Description
parameter_name	yes	-	The name of the group that the current group is dependent upon. for example, page2.isbreaking
value_equals	yes	-	The value the target parameter must equal for this condition to be considered true.

ValueNotEqualsCondition

Properties:

Property	Required	Default Value	Description
parameter_name	yes	-	The name of the group that the current group is dependent upon.
value_not_equals	yes	-	The value the target parameter must not equal for this condition to be considered true.

ValueContainsCondition

Properties:

Property	Required	Default Value	Description
parameter_name	yes	-	The name of the group that the current group is dependent upon.
value_contains	yes	-	A value the target parameter must contain for this condition to be considered true.

ValueNotContainsCondition

Properties:

Property	Required	Default Value	Description
parameter_name	yes	-	The name of the group that the current group is dependent upon.
value_not_contains	yes	-	A value the target parameter must not contain for this condition to be considered true.

ValueEmptyCondition

Properties:

Property	Required	Default Value	Description
parameter_name	yes	-	The name of the group that the current group is dependent upon.
value_empty	yes	-	A bool value reflecting whether the expected parameter should be empty or not.

Multiple Templates

You can define multiple templates in the .czrc file, separated by ---：

name: angular-templateitems:
# ... format: "{{.type}}{{with .scope}}({{.}}){{end}}: {{.subject}}{{with .body}}\n\n{{.}}{{end}}{{with .footer}}\n\n{{.}}{{end}}"`---name: my-templateitems:# ... format: "{{.type}}{{with .scope}}({{.}}){{end}}: {{.subject}}{{with .body}}\n\n{{.}}{{end}}{{with .footer}}\n\n{{.}}{{end}}"`