Added documentation for the show command

Author: coordt

README.md

@@ -48,15 +48,19 @@ pip install --upgrade bump-my-version
 
 Please find the changelog here: [CHANGELOG.md](CHANGELOG.md)
 
-## Usage
+## Usage for version incrementing
 
 > **NOTE:** 
 >
 > Throughout this document, you can use `bumpversion` or `bump-my-version` interchangeably.
 
-There are two modes of operation: On the command line for single-file operation and using a configuration file for more complex multi-file operations.
+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.
 
-    bump-my-version [options] part [file]
+> **WARNING:**
+> 
+> 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.
+
+    bump-my-version bump [options] [part] [file]
 
 ### `part`
 
@@ -68,7 +72,7 @@ Valid values include the named groups defined in the `parse` configuration.
 
 Example bumping 0.5.1 to 0.6.0:
 
-    bump-my-version --current-version 0.5.1 minor
+    bump-my-version bump --current-version 0.5.1 minor
 
 ### `file`
 
@@ -81,7 +85,7 @@ These files are added to the list of files specified in your configuration file.
 
 Example bumping 1.1.9 to 2.0.0:
 
-    bump-my-version --current-version 1.1.9 major setup.py
+    bump-my-version bump --current-version 1.1.9 major setup.py
 
 ## Configuration file
 
@@ -115,7 +119,7 @@ Similar to dry-run, but will also avoid checking the files. Also useful when you
 Print useful information to stderr. If specified more than once, it will output more information.
 
 `--list`
-List machine-readable information to stdout for consumption by other programs.
+_DEPRECATED. Use `bump-my-version show` instead._ List machine-readable information to stdout for consumption by other programs.
 
 Example output:
 
@@ -127,19 +131,22 @@ Print help and exit
 
 ## Using bumpversion in a script
 
-If you need to use the version generated by bumpversion in a script, you can make use of the `--list` option combined with `grep` and `sed`.
+If you need to use the version generated by bumpversion in a script, you can make use of the `show` subcommand.
 
 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.
 
 The standard way to get it in a bash script is
 
-    bump-my-version --dry-run --list <part> | grep <field name> | sed -r s,"^.*=",,
+    bump-my-version show new_version --increment <part>
 
-where `part` is the part of the version number you are updating. You need to specify `--dry-run` to avoid bumpversion acting.
+where `part` is the part of the version number you are updating.
 
-For example, if you are updating the minor number and looking for the new version number, this becomes
+For example, if you are updating the minor number and looking for the new version number, this becomes:
 
-    bump-my-version --dry-run --list minor | grep new_version | sed -r s,"^.*=",,
+```console
+$ bump-my-version show new_version --increment minor
+1.1.0
+```
 
 ## Development & Contributing
 

docsrc/usage.md

@@ -5,46 +5,94 @@
 Throughout this document, you can use `bumpversion` or `bump-my-version` interchangeably.
 ```
 
-There are two modes of operation: On the command line for single-file operation
-and using a configuration file (`pyproject.toml`) for more complex multi-file operations.
+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 processes.
+
+```{admonition} WARNING
+
+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.
+```
+## Incrementing a version
 
 ```console
-bump-my-version [OPTIONS] [VERSION_PART] [FILES]...
+bump-my-version bump [OPTIONS] [ARGS]...
 ```
 
-## `VERSION_PART`
+The `bump` sub-command triggers a version increment. The [complete list of options](cli.rst#bumpversion-bump) is available. The `ARGS` may contain a `VERSION_PART` or `FILES`
+
+
+### `VERSION_PART`
 
 _**[optional]**_
 
-The part of the version to increase, e.g. `minor`.
+The part of the version to increase, e.g., `minor`.
 
-Valid values include those given in the `--serialize` / `--parse` option.
+Valid values include those given in the [`--serialize`](configuration.md#serialize) / [`--parse`](configuration.md#parse) option.
 
 Example bumping 0.5.1 to 0.6.0:
 
 ```console
-bump-my-version --current-version 0.5.1 minor src/VERSION
+bump-my-version bump --current-version 0.5.1 minor src/VERSION
 ```
 
 
-## `FILES`
+### `FILES`
 
 _**[optional]**_<br />
 **default**: `None`
 
 The additional file(s) to modify.
 
-This file is added to the list of files specified in the configuration file. If you want to rewrite only files
-specified on the command line, use `--no-configured-files`.
+This file is added to the list of files specified in the configuration file. If you want to rewrite only files specified on the command line, use `--no-configured-files`.
 
 Example bumping version 1.1.9 to 2.0.0 in the `setup.py` file:
 
 ```console
-bump-my-version --current-version 1.1.9 major setup.py
+bump-my-version bump --current-version 1.1.9 major setup.py
 ```
 
 Example bumping version 1.1.9 to 2.0.0 in _only_ the `setup.py` file:
 
 ```console
-bump-my-version --current-version 1.1.9 --no-configured-files major setup.py
+bump-my-version bump --current-version 1.1.9 --no-configured-files major setup.py
+```
+
+## Showing configuration information
+
+```console
+bump-my-version show [OPTIONS] [ARGS]
+```
+
+The `show` subcommand allows you to output the entire or parts of the configuration to the console. The default invocation will output in the default format. The default format changes if one or more than one item is requested. If more than one item is asked for, it outputs the result of Python's `pprint` function. If only one thing is asked for, it outputs that value only.
+
+```console
+$ bump-my-version show current_version
+1.0.0
+$ bump-my-version show current_version commit
+{'current_version': '1.0.0', 'commit': False}
+```
+
+You can use the `--increment` option to enable a `new_version` key.
+
+```console
+$ bump-my-version show --increment minor current_version new_version
+{'current_version': '1.0.0', 'new_version': '1.1.0'}
+```
+
+You can also specify the output to be in JSON or YAML format:
+
+```console
+$ bump-my-version show --format yaml current_version
+current_version: "1.0.0"
+$ bump-my-version show --format yaml current_version commit
+current_version: "1.0.0"
+commit: false
+$ bump-my-version show --format json current_version
+{
+  "current_version": "1.0.0"
+}
+$ bump-my-version show --format json current_version commit
+{
+  "current_version": "1.0.0",
+  "commit": false,
+}
 ```

docsrc/version-parts.md

@@ -20,8 +20,8 @@ The `serialize` configuration value is a list of default formats. You have the o
 
 ```toml
 serialize = [
-		"{major}.{minor}.{patch}",
-		"{major}.{minor}",
+    "{major}.{minor}.{patch}",
+    "{major}.{minor}",
 ]
 ```