You signed in with another tab or window. Reload to refresh your session.You signed out in another tab or window. Reload to refresh your session.You switched accounts on another tab or window. Reload to refresh your session.Dismiss alert
Please find the changelog here: [CHANGELOG.md](CHANGELOG.md)
46
46
47
-
## Usage for version incrementing
48
-
49
-
There are two modes of operation: On the command line for single-file operation and using a configuration file (`pyproject.toml` or `.bumpversion.toml`) for more complex multi-file operations.
50
-
51
-
> **WARNING:**
52
-
>
53
-
> The invocation of `bump-my-version` changed in version 0.6.0. It split functionality into sub-commands. It remains backward-compatible with previous versions. Previous usage is discouraged and may be removed in a 1.0 release.
54
-
55
-
bump-my-version bump [options] [part] [file]
56
-
57
-
### `part`
58
-
59
-
_**required**_
60
-
61
-
The part of the version to increase, e.g. `minor`.
62
-
63
-
Valid values include the named groups defined in the `parse` configuration.
64
-
65
-
Example bumping 0.5.1 to 0.6.0:
66
-
67
-
bump-my-version bump --current-version 0.5.1 minor
68
-
69
-
### `file`
70
-
71
-
_**[optional]**_<br />
72
-
**default**: none
73
-
74
-
Additional files to modify.
47
+
## Semantic versioning example
48
+
<!--tutorial start-->
49
+
50
+
### Create a default configuration
51
+
52
+
The default configuration uses a simplified version of [semantic versioning](https://semver.org/).
53
+
54
+
```console title="Generating a default configuration"
These files are added to the list of files specified in your configuration file. If you want to rewrite only files specified on the command line, also use `--no-configured-files`.
75
+
### Visualize the versioning path
77
76
78
-
Example bumping 1.1.9 to 2.0.0:
77
+
You can see the potential versioning paths with the `show-bump` subcommand.
79
78
80
-
bump-my-version bump --current-version 1.1.9 major setup.py
79
+
```console title="Showing the potential versioning path"
80
+
$ bump-my-version show-bump
81
+
0.1.0 ── bump ─┬─ major ─ 1.0.0
82
+
├─ minor ─ 0.2.0
83
+
╰─ patch ─ 0.1.1
84
+
$ bump-my-version show-bump 1.2.3
85
+
1.2.3 ── bump ─┬─ major ─ 2.0.0
86
+
├─ minor ─ 1.3.0
87
+
╰─ patch ─ 1.2.4
88
+
```
81
89
82
-
## Configuration file
90
+
The default configuration only allows bumping the major, minor, or patch version. What if you wanted to support pre-release versions?
83
91
84
-
`bump-my-version` looks in four places for the configuration file to parse (in order of precedence):
Alter the `parse` configuration to support pre-release versions. This `parse` option uses an extended (or verbose) regular expression to extract the version parts from the current version.
92
95
93
-
`.toml` files are recommended due to their type handling. We will likely drop support for `ini`-style formats in the future due to issues with formatting and parsing. You should add your configuration file to your source code management system.
96
+
```toml title="New parse configuration"
97
+
parse = """(?x)
98
+
(?P<major>0|[1-9]\\d*)\\.
99
+
(?P<minor>0|[1-9]\\d*)\\.
100
+
(?P<patch>0|[1-9]\\d*)
101
+
(?:
102
+
- # dash seperator for pre-release section
103
+
(?P<pre_l>[a-zA-Z-]+) # pre-release label
104
+
(?P<pre_n>0|[1-9]\\d*) # pre-release version number
105
+
)? # pre-release section is optional
106
+
"""
107
+
```
94
108
95
-
By using a configuration file, you no longer need to specify those options on the command line. The configuration file also allows greater flexibility in specifying how files are modified.
109
+
Alter the `serialize` configuration to support pre-release versions.
96
110
97
-
## Command-line Options
111
+
```toml title="New serialize configuration"
112
+
serialize = [
113
+
"{major}.{minor}.{patch}-{pre_l}{pre_n}",
114
+
"{major}.{minor}.{patch}",
115
+
]
116
+
```
98
117
99
-
Most of the configuration values above can also be given as an option on the command line.
100
-
Additionally, the following options are available:
118
+
Add a new configuration section for the `pre_l` part.
101
119
102
-
`--dry-run, -n`
103
-
Don't touch any files, just pretend. Best used with `--verbose`.
120
+
```toml title="New pre_l configuration"
104
121
105
-
`--no-configured-files`
106
-
Will not update/check files specified in the configuration file.
122
+
[tool.bumpversion.parts.pre_l]
123
+
values = ["dev", "rc", "final"]
124
+
optional_value = "final"
125
+
```
107
126
108
-
Similar to dry-run, but will also avoid checking the files. Also useful when you want to update just one file with e.g., `bump-my-version --no-configured-files major my-file.txt`
127
+
### Visualize the new versioning path
109
128
110
-
`--verbose, -v`
111
-
Print useful information to stderr. If specified more than once, it will output more information.
129
+
Now when you run `bump-my-version show-bump`, you can see the new pre-release versioning path.
112
130
113
-
`--list`
114
-
_DEPRECATED. Use `bump-my-version show` instead._ List machine-readable information to stdout for consumption by other programs.
131
+
```console title="Showing the new versioning path"
132
+
$ bump-my-version show-bump
133
+
0.1.0 ── bump ─┬─ major ─ 1.0.0-dev0
134
+
├─ minor ─ 0.2.0-dev0
135
+
├─ patch ─ 0.1.1-dev0
136
+
├─ pre_l ─ invalid: The part has already the maximum value among ['dev', 'rc', 'final'] and cannot be bumped.
137
+
╰─ pre_n ─ 0.1.0-final1
138
+
```
115
139
116
-
Example output:
140
+
The `pre_l` is not bump-able because it is already at the maximum value. The `pre_n` is bump-able because it is not at the maximum value.
117
141
118
-
current_version=0.0.18
119
-
new_version=0.0.19
142
+
If we run `bump-my-version show-bump 1.0.0-dev0`, we can see the new versioning path for a `dev` starting version.
120
143
121
-
`-h, --help`
122
-
Print help and exit
144
+
```console title="Showing the new versioning path for a dev version"
145
+
$ bump-my-version show-bump 1.0.0-dev0
146
+
1.0.0-dev0 ── bump ─┬─ major ─ 2.0.0-dev0
147
+
├─ minor ─ 1.1.0-dev0
148
+
├─ patch ─ 1.0.1-dev0
149
+
├─ pre_l ─ 1.0.0-rc0
150
+
╰─ pre_n ─ 1.0.0-dev1
151
+
```
123
152
124
-
## Using Bump My Version in a script
153
+
Finally, we can see the new versioning path for a `rc` starting version.
125
154
126
-
If you need to use the version generated by Bump My Version in a script, you can make use of the `show` subcommand.
155
+
```console title="Showing the new versioning path for an rc version"
156
+
$ bump-my-version show-bump 1.0.0-rc0
157
+
1.0.0-rc0 ── bump ─┬─ major ─ 2.0.0-dev0
158
+
├─ minor ─ 1.1.0-dev0
159
+
├─ patch ─ 1.0.1-dev0
160
+
├─ pre_l ─ 1.0.0
161
+
╰─ pre_n ─ 1.0.0-rc1
162
+
```
127
163
128
-
Say, for example, that you are using git-flow to manage your project and want to automatically create a release. When you issue `git flow release start` you need to know the new version before applying the change.
164
+
The full development and release path is:
129
165
130
-
The standard way to get it in a bash script is
166
+
-`1.0.0`
167
+
-`bump patch` → `1.0.1-dev0`
168
+
-`bump pre_n` → `1.0.1-dev1`
169
+
-`bump pre_l` → `1.0.1-rc0`
170
+
-`bump pre_n` → `1.0.1-rc1`
171
+
-`bump pre_l` → `1.0.1`
131
172
132
-
bump-my-version show new_version --increment <part>
173
+
1. You must decide on the next version before you start developing.
174
+
2. Development versions increase using `bump-my-version bump pre_n`.
175
+
3. Switch from development to release candidate using `bump-my-version bump pre_l`.
176
+
4. Release candidates increase using `bump-my-version bump pre_n`.
177
+
5. Switch from the release candidate to the final release using `bump-my-version bump pre_l`.
133
178
134
-
where `part` is the part of the version number you are updating.
179
+
### Automate the pre-release numbering
135
180
136
-
For example, if you are updating the minor number and looking for the new version number, this becomes:
181
+
The `pre_n` or pre-release number is a number that increases with each pre-release. You can automate this my changing the serialization configuration.
137
182
138
-
```console
139
-
$ bump-my-version show new_version --increment minor
140
-
1.1.0
183
+
```toml title="Serialize configuration with pre_n automation"
The `distance_to_latest_tag` is a special value that is replaced with the number of commits since the last tag. This is a good value to use for the `pre_n` because it will always increase with each commit.
191
+
192
+
### Visualize the pre_n versioning path
193
+
194
+
Now when you run `bump-my-version show-bump`, you can see the new pre-release versioning path.
195
+
196
+
```console title="Showing the new versioning path with pre_n automation"
197
+
198
+
$ bump-my-version show-bump
199
+
0.1.0 ── bump ─┬─ major ─ 1.0.0-dev0
200
+
├─ minor ─ 0.2.0-dev0
201
+
├─ patch ─ 0.1.1-dev0
202
+
╰─ pre_l ─ invalid: The part has already the maximum value among ['dev', 'rc', 'final'] and cannot be bumped.
203
+
$ bump-my-version show-bump 1.0.0-dev0
204
+
1.0.0-dev0 ── bump ─┬─ major ─ 2.0.0-dev0
205
+
├─ minor ─ 1.1.0-dev0
206
+
├─ patch ─ 1.0.1-dev0
207
+
╰─ pre_l ─ 1.0.0-rc0
208
+
$ bump-my-version show-bump 1.0.0-rc0
209
+
1.0.0-rc0 ── bump ─┬─ major ─ 2.0.0-dev0
210
+
├─ minor ─ 1.1.0-dev0
211
+
├─ patch ─ 1.0.1-dev0
212
+
╰─ pre_l ─ 1.0.0
213
+
```
214
+
215
+
The `pre_n` path is now missing because it is automated.
216
+
217
+
The full development and release path now is:
218
+
219
+
-`1.0.0`
220
+
-`bump patch` → `1.0.1-dev0`
221
+
- each commit will increase → `1.0.1-dev1`
222
+
-`bump pre_l` → `1.0.1-rc0`
223
+
- each commit will increase → `1.0.1-rc1`
224
+
-`bump pre_l` → `1.0.1`
225
+
226
+
1. You must decide on the next version before you start developing.
227
+
2. Development versions increase automatically with each commit.
228
+
3. Switch from development to release candidate using `bump-my-version bump pre_l`.
229
+
4. Release candidate versions increase automatically with each commit.
230
+
5. Switch from the release candidate to the final release using `bump-my-version bump pre_l`.
231
+
232
+
<!--tutorial end-->
233
+
143
234
## Development & Contributing
144
235
145
236
Thank you, contributors! You can find a full list here: https://github.com/callowayproject/bump-my-version/graphs/contributors
0 commit comments