Skip to content

Commit 4a0d5bb

Browse files
shipengqishipengqi
committed
docs(items): add more details of item types
1 parent e3b77be commit 4a0d5bb

File tree

1 file changed

+155
-41
lines changed

1 file changed

+155
-41
lines changed

‎README.md‎

Lines changed: 155 additions & 41 deletions
Original file line numberDiff line numberDiff line change
@@ -72,6 +72,7 @@ $ git cz
7272
Download the pre-compiled binaries from the [releases page](https://github.com/shipengqi/commitizen/releases) and copy them to the desired location.
7373

7474
Then install this tool to git-core as git-cz:
75+
7576
```
7677
$ commitizen init
7778
```
@@ -97,79 +98,192 @@ $ make && ./_output/$(GOOS)/$(GOARCH)/bin/commitizen init
9798

9899
## Configuration
99100

100-
You can set configuration file that `.git-czrc` at repository root or home directory. The configuration file that located in repository root have a priority over the one in home directory. The format is the same as the following:
101+
You can set configuration file that `.czrc` at repository root or home directory. The configuration file that located in repository root have a priority over the one in home directory. The format is the same as the following:
101102

102103
```yaml
103104
name: my-default
104105
default: true # (optional) If true, this template will be used as the default template, note that there can only be one default template
105106
items:
106107
- name: type
107-
desc: "Select the type of change that you're committing:"
108-
type: select
108+
group: page1
109+
label: "Select the type of change that you're committing:"
110+
type: list
109111
options:
110-
- name: feat
111-
desc: "A new feature"
112-
- name: fix
113-
desc: "A bug fix"
114-
- name: docs
115-
desc: "Documentation only changes"
116-
- name: test
117-
desc: "Adding missing tests"
118-
- name: WIP
119-
desc: "Work in progress"
120-
- name: chore
121-
desc: "Changes to the build process or auxiliary tools\n and libraries such as documentation generation"
122-
- name: style
123-
desc: "Changes that do not affect the meaning of the code\n (white-space, formatting, missing semi-colons, etc)"
124-
- name: refactor
125-
desc: "A code change that neither fixes a bug nor adds a feature"
126-
- name: perf
127-
desc: "A code change that improves performance"
128-
- name: revert
129-
desc: "Revert to a commit"
112+
- value: feat
113+
key: "feat: A new feature"
114+
- value: fix
115+
key: "fix: A bug fix"
116+
- value: docs
117+
key: "docs: Documentation only changes"
118+
- value: test
119+
key: "test: Adding missing or correcting existing tests"
120+
- value: chore
121+
key: "chore: Changes to the build process or auxiliary tools and\n libraries such as documentation generation"
122+
- value: style
123+
key: "style: Changes that do not affect the meaning of the code\n (white-space, formatting, missing semi-colons, etc)"
124+
- value: refactor
125+
key: "refactor: A code change that neither fixes a bug nor adds a feature"
126+
- value: perf
127+
key: "perf: A code change that improves performance"
128+
- value: revert
129+
key: "revert: Reverts a previous commit"
130130
- name: scope
131-
desc: "Scope. Could be anything specifying place of the commit change:"
132-
type: input
131+
group: page2
132+
label: "Scope. What is the scope of this change? (class or file name):"
133+
type: string
134+
regex: ^[a-zA-Z0-9]+
133135
- name: subject
134-
desc: "Subject. Concise description of the changes. Imperative, lower case and no final dot:"
135-
type: input
136-
required: true # (optional) If true, enable a validator that requires the control have a non-empty value.
136+
group: page2
137+
label: "Subject. Write a short and imperative summary of the code change (lower case and no period):"
138+
type: string
139+
required: true
137140
- name: body
138-
desc: "Body. Motivation for the change and contrast this with previous behavior:"
139-
type: textarea
141+
group: page3
142+
label: "Body. Provide additional contextual information about the code changes:"
143+
type: text
140144
- name: footer
141-
desc: "Footer. Information about Breaking Changes and reference issues that this commit closes:"
142-
type: textarea
145+
group: page3
146+
label: "Footer. Information about Breaking Changes and reference issues that this commit closes:"
147+
type: text
143148
format: "{{.type}}{{with .scope}}({{.}}){{end}}: {{.subject}}{{with .body}}\n\n{{.}}{{end}}{{with .footer}}\n\n{{.}}{{end}}"`
144149
```
145150

151+
### Format
152+
146153
Commit message `format`:
147154

148155
```
149156
format: "{{.type}}{{with .scope}}({{.}}){{end}}: {{.subject}}{{with .body}}\n\n{{.}}{{end}}{{with .footer}}\n\n{{.}}{{end}}"
150157
```
151158

159+
### Items
160+
161+
#### Common Item Properties
162+
163+
| Property | Required | Default Value | Description |
164+
|:------------|:---------|:--------------|:--------------------------------------------------------------------------------------------------------------------|
165+
| name | yes | - | Unique identifier for the item. |
166+
| label | yes | - | This will be used as the label for the input field in the UI. |
167+
| type | yes | - | The type of item. Determines which UI widget is shown. See the Item Types section to see all the different options. |
168+
| group | no | - | The name of the group this item belongs to. |
169+
| description | no | - | A short description of the item for user guidance. This will be displayed along with the input field. |
170+
171+
#### Item Types
172+
173+
- string
174+
- text
175+
- integer
176+
- boolean
177+
- secret
178+
- list
179+
- multi_list
180+
181+
#### string
182+
183+
`string` are single line text parameters.
184+
185+
Properties:
186+
187+
| Property | Required | Default Value | Description |
188+
|:--------------|:---------|:--------------|:-------------------------------------------------------------------------------------------------------------|
189+
| required | no | `false` | Whether a string value is required or not. |
190+
| fqdn | no | `false` | Add a preset FQDN regex to validate string. |
191+
| ip | no | `false` | Add a preset IPv4/IPv6 regex to validate string. |
192+
| default_value | no | - | The default value for this item. |
193+
| regex | no | - | A regex used to validate the string. |
194+
| min_length | no | - | The minimum length of the string. If the value is not required and no value has been given, this is ignored. |
195+
| max_length | no | - | The maximum length of the string. |
196+
197+
#### text
198+
199+
Properties:
200+
201+
| Property | Required | Default Value | Description |
202+
|:--------------|:---------|:--------------|:-----------------------------------------------------------------------------------------------------------|
203+
| required | no | `false` | Whether the text is required or not. |
204+
| height | no | 5 | The height of the text. |
205+
| default_value | no | - | The default value for this item. |
206+
| regex | no | - | A regex used to validate the text. |
207+
| min_length | no | - | The minimum length of the text. If the value is not required and no value has been given, this is ignored. |
208+
| max_length | no | - | The maximum length of the text. |
209+
210+
#### integer
211+
212+
`integer` is a number.
213+
214+
Properties:
215+
216+
| Property | Required | Default Value | Description |
217+
|:--------------|:---------|:--------------|:----------------------------------------|
218+
| required | no | `false` | Whether the integer is required or not. |
219+
| default_value | no | - | The default value for this item. |
220+
| min | no | - | The minimum value allowed. |
221+
| max | no | - | The maximum value allowed. |
222+
223+
#### boolean
224+
225+
`boolean` are true or false values.
226+
227+
Properties:
228+
229+
| Property | Required | Default Value | Description |
230+
|:--------------|:---------|:--------------|:---------------------------------|
231+
| default_value | no | - | The default value for this item. |
232+
233+
#### secret
234+
235+
`secret` is used for sensitive data that should not be echoed in the UI, for example, passwords.
236+
237+
Properties:
238+
239+
| Property | Required | Default Value | Description |
240+
|:--------------|:---------|:--------------|:-------------------------------------------------------------------------------------------------------------|
241+
| required | no | `false` | Whether the secret is required or not. |
242+
| default_value | no | - | The default value for this item. |
243+
| regex | no | - | A regex used to validate the secret. |
244+
| min_length | no | - | The minimum length of the secret. If the value is not required and no value has been given, this is ignored. |
245+
| max_length | no | - | The maximum length of the secret. |
246+
247+
#### list
248+
249+
`list` is predefined lists of values that can be picked by the user.
250+
251+
Properties:
252+
253+
| Property | Required | Default Value | Description |
254+
|:--------------|:---------|:--------------|:-------------------------------------------|
255+
| required | no | `false` | Whether a string value is required or not. |
256+
| default_value | no | - | The default value for this item. |
257+
| options | yes | - | The list of options to choose from. |
258+
259+
#### multi_list
260+
261+
Similar to `list`, but with multiple selection.
262+
263+
Properties:
264+
265+
| Property | Required | Default Value | Description |
266+
|:--------------|:---------|:--------------|:-------------------------------------------|
267+
| required | no | `false` | Whether a string value is required or not. |
268+
| default_value | no | - | The default value for this item. |
269+
| options | yes | - | The list of options to choose from. |
270+
| limit | no | `false` | The limit of the multiple selection list. |
271+
152272
### Multiple Templates
153273

154-
You can define multiple templates in the `.git-czrc` file, separated by `---`：
274+
You can define multiple templates in the `.czrc` file, separated by `---`：
155275

156276
```yaml
157277
name: angular-template
158278
items:
159-
- name: scope
160-
desc: "Scope. Could be anything specifying place of the commit change:"
161-
type: input
162-
# ...
279+
# ...
163280
format: "{{.type}}{{with .scope}}({{.}}){{end}}: {{.subject}}{{with .body}}\n\n{{.}}{{end}}{{with .footer}}\n\n{{.}}{{end}}"`
164281

165282
---
166283

167284
name: my-template
168285
items:
169-
- name: scope
170-
desc: "Scope. Could be anything specifying place of the commit change:"
171-
type: input
172-
# ...
286+
# ...
173287
format: "{{.type}}{{with .scope}}({{.}}){{end}}: {{.subject}}{{with .body}}\n\n{{.}}{{end}}{{with .footer}}\n\n{{.}}{{end}}"`
174288
```
175289

0 commit comments

Comments
 (0)