diff --git a/.github/workflows/version.yaml b/.github/workflows/release.yaml similarity index 100% rename from .github/workflows/version.yaml rename to .github/workflows/release.yaml diff --git a/CHANGELOG.md b/CHANGELOG.md index 28ad17e3..6bb4859b 100644 --- a/CHANGELOG.md +++ b/CHANGELOG.md @@ -1,5 +1,18 @@ # Changelog +## 0.22.0 (2024-06-11) +[Compare the full difference.](https://github.com/callowayproject/bump-my-version/compare/0.21.1...0.22.0) + +### New + +- Add extensive documentation for the 'show' subcommand. [91409d8](https://github.com/callowayproject/bump-my-version/commit/91409d81d647a6dc1e39d3cfbc1e0e95a5c67a82) + + This commit adds extensive documentation for the `show` subcommand in the program's reference. It also includes smaller updates and corrections to other parts of the documentation. An in-depth example usage of `show` is added both to the dedicated `show.md` file and in the function's docstring. +### Updates + +- Renamed version workflow to release. [68f9eee](https://github.com/callowayproject/bump-my-version/commit/68f9eee8f953c23d30b8ef77a3cedf9355ce55a0) + + ## 0.21.1 (2024-05-16) [Compare the full difference.](https://github.com/callowayproject/bump-my-version/compare/0.21.0...0.21.1) diff --git a/bumpversion/__init__.py b/bumpversion/__init__.py index 69b64a79..3a347643 100644 --- a/bumpversion/__init__.py +++ b/bumpversion/__init__.py @@ -1,3 +1,3 @@ """Top-level package for bump-my-version.""" -__version__: str = "0.21.1" +__version__: str = "0.22.0" diff --git a/bumpversion/cli.py b/bumpversion/cli.py index 78de24f3..3df3ff21 100644 --- a/bumpversion/cli.py +++ b/bumpversion/cli.py @@ -338,7 +338,19 @@ def bump( help="Increment the version part and add `new_version` to the configuration.", ) def show(args: List[str], config_file: Optional[str], format_: str, increment: Optional[str]) -> None: - """Show current configuration information.""" + """ + Show current configuration information. + + ARGS may contain one or more configuration attributes. For example: + + - `bump-my-version show current_version` + + - `bump-my-version show files.0.filename` + + - `bump-my-version show scm_info.branch_name` + + - `bump-my-version show current_version scm_info.distance_to_latest_tag` + """ found_config_file = find_config_file(config_file) config = get_configuration(found_config_file) diff --git a/docs/reference/cli.md b/docs/reference/cli.md index 7e32e484..28232b13 100644 --- a/docs/reference/cli.md +++ b/docs/reference/cli.md @@ -1,3 +1,5 @@ +# CLI Reference + ::: mkdocs-click :module: bumpversion.cli :command: cli diff --git a/docs/reference/configuration.md b/docs/reference/configuration.md index 8779ab06..39fe95c8 100644 --- a/docs/reference/configuration.md +++ b/docs/reference/configuration.md @@ -68,7 +68,7 @@ Bump-my-version's default behavior is to abort if the working directory has unco Whether to create a commit using git or Mercurial. -If you have pre-commit hooks, you might also want to add an option to [`commit_args`](configuration.md#commit-args) to disable your pre-commit hooks. For Git use `--no-verify` and use `--config hooks.pre-commit=` for Mercurial. +If you have pre-commit hooks, you might also want to add an option to [`commit_args`](configuration.md#commit_args) to disable your pre-commit hooks. For Git use `--no-verify` and use `--config hooks.pre-commit=` for Mercurial. ### commit_args @@ -339,7 +339,7 @@ If `True`, sign the created tag, when [`tag`](configuration.md#tag) is `True`. environment var : `BUMPVERSION_TAG` -If `True`, create a tag after committing the changes. The tag is named using the [`tag_name`](configuration.md#tag-name) option. +If `True`, create a tag after committing the changes. The tag is named using the [`tag_name`](configuration.md#tag_name) option. If you are using `git`, don't forget to `git-push` with the `--tags` flag when you are done. @@ -533,7 +533,7 @@ When this value is set to `True`, the part is always incremented when the versio type : string -The `calver_format` is a string that specifies the format of the version part. It is used to determine the next value when bumping the version. The format is a string that uses the placeholders defined in the [CalVer reference](calver_reference.md#calver-format). +The `calver_format` is a string that specifies the format of the version part. It is used to determine the next value when bumping the version. The format is a string that uses the placeholders defined in the [CalVer reference](calver_reference.md#calver_format). ### Examples diff --git a/docs/reference/index.md b/docs/reference/index.md index a74ae62a..086c4f99 100644 --- a/docs/reference/index.md +++ b/docs/reference/index.md @@ -1,8 +1,9 @@ # Reference - +- [Subcommands](subcommands/index.md) - [Command-line interface](cli.md) - [Configuration](configuration.md) +- [Calendar versioning reference](calver_reference.md) - [Formatting context](formatting-context.md) - [Version parts](version-parts.md) - [Search and replace configuration](search-and-replace-config.md) diff --git a/docs/reference/subcommands/index.md b/docs/reference/subcommands/index.md new file mode 100644 index 00000000..ec7b3f28 --- /dev/null +++ b/docs/reference/subcommands/index.md @@ -0,0 +1,9 @@ +# Subcommand reference + +Bump-my-version uses subcommands to focus its functionality. + +- `bump` triggers the version incrementing workflow +- `replace` replaces the version in files without triggering a version increment. +- `sample-config` helps new users configure bumpy-my-version by printing a sample configuration file. +- `show` provides access to current configuration information. +- `show-bump` helps developers understand the current versioning convention by showing the possible versions resulting from the `bump` subcommand. diff --git a/docs/reference/subcommands/show.md b/docs/reference/subcommands/show.md new file mode 100644 index 00000000..e90f0acc --- /dev/null +++ b/docs/reference/subcommands/show.md @@ -0,0 +1,53 @@ +# The show subcommand + +The main purpose of the `show` subcommand is to provide access to configuration data via scripts. + +## Basic use + +The configuration object is a `dict` containing nested data structures. The arguments and options of this command relate to extracting data from the configuration object and presenting the extracted data. + +## Specifying the output data + +The positional arguments determine the data shown. If nothing or `all` is passed, the entire configuration is shown. + +Positional arguments are specified using a format like [Django variable resolution](https://docs.djangoproject.com/en/5.0/ref/templates/language/#variables). + +Examples: + +- `a.b` specifies the "b" key in the nested dictionaries: `{"a": {"b": "value"}}` +- `a.3` specifies the 4th item (the first is 0) of the list at key "a": `{"a": ["no", "nay", "nyet", "value"]}` + +## Specifying the output format + +If only one positional argument is passed, the default format only shows its value. If no positional arguments, several positional arguments, or `all` is passed, the output from [`pprint.pprint`](https://docs.python.org/3.12/library/pprint.html#pprint.pprint) is shown. + +This makes getting the current version easy: + +```console +$ bump-my-version show current_version +1.0.1 +``` + +You can request the output be formatted as YAML or JSON: + +```console +$ bump-my-version show --format yaml current_version +current_version: "1.0.1" +$ bump-my-version show --format json current_version +{ + "current_version": "1.0.1" +} +``` + +## Including the incremented version before bumping + +Your workflow might want to know the new version before you actually do the bumping. The `--increment` or `-i` option accepts a version part to bump and adds a `new_version` key into the configuration. + +```console +$ bump-my-version --increment patch show +1.0.2 +$ bump-my-version --increment minor show +1.1.0 +$ bump-my-version --increment major show +2.0.0 +``` diff --git a/pyproject.toml b/pyproject.toml index cddf1085..aa9b8019 100644 --- a/pyproject.toml +++ b/pyproject.toml @@ -216,7 +216,7 @@ order-by-type = true convention = "google" [tool.bumpversion] -current_version = "0.21.1" +current_version = "0.22.0" commit = true commit_args = "--no-verify" tag = true