fix(cli/commands): add description for subcommands

Author: marcosdotme

commitizen/cli.py

@@ -114,11 +114,13 @@ def __call__(
         "commands": [
             {
                 "name": ["init"],
+                "description": "init commitizen configuration",
                 "help": "init commitizen configuration",
                 "func": commands.Init,
             },
             {
                 "name": ["commit", "c"],
+                "description": "create new commit",
                 "help": "create new commit",
                 "func": commands.Commit,
                 "arguments": [
@@ -164,22 +166,31 @@ def __call__(
             },
             {
                 "name": "ls",
+                "description": "show available commitizens",
                 "help": "show available commitizens",
                 "func": commands.ListCz,
             },
             {
                 "name": "example",
+                "description": "show commit example",
                 "help": "show commit example",
                 "func": commands.Example,
             },
             {
                 "name": "info",
+                "description": "show information about the cz",
                 "help": "show information about the cz",
                 "func": commands.Info,
             },
-            {"name": "schema", "help": "show commit schema", "func": commands.Schema},
+            {
+                "name": "schema",
+                "description": "show commit schema",
+                "help": "show commit schema",
+                "func": commands.Schema,
+            },
             {
                 "name": "bump",
+                "description": "bump semantic version based on the git log",
                 "help": "bump semantic version based on the git log",
                 "func": commands.Bump,
                 "arguments": [
@@ -346,6 +357,9 @@ def __call__(
             },
             {
                 "name": ["changelog", "ch"],
+                "description": (
+                    "generate changelog (note that it will overwrite existing file)"
+                ),
                 "help": (
                     "generate changelog (note that it will overwrite existing file)"
                 ),
@@ -416,6 +430,7 @@ def __call__(
             },
             {
                 "name": ["check"],
+                "description": "validates that a commit message matches the commitizen schema",
                 "help": "validates that a commit message matches the commitizen schema",
                 "func": commands.Check,
                 "arguments": [
@@ -455,6 +470,10 @@ def __call__(
             },
             {
                 "name": ["version"],
+                "description": (
+                    "get the version of the installed commitizen or the current project"
+                    " (default: installed commitizen)"
+                ),
                 "help": (
                     "get the version of the installed commitizen or the current project"
                     " (default: installed commitizen)"

tests/commands/test_bump_command.py

@@ -1449,3 +1449,15 @@ def test_bump_changelog_contains_increment_only(mocker, tmp_commitizen_project,
 
     assert "3.0.0" in out
     assert "2.0.0" not in out
+
+
+def test_bump_command_shows_description_when_use_help_option(
+    mocker: MockFixture, capsys, file_regression
+):
+    testargs = ["cz", "bump", "--help"]
+    mocker.patch.object(sys, "argv", testargs)
+    with pytest.raises(SystemExit):
+        cli.main()
+
+    out, _ = capsys.readouterr()
+    file_regression.check(out, extension=".txt")

tests/commands/test_bump_command/test_bump_command_shows_description_when_use_help_option.txt

@@ -0,0 +1,79 @@
+usage: cz bump [-h] [--dry-run] [--files-only] [--local-version] [--changelog]
+               [--no-verify] [--yes] [--tag-format TAG_FORMAT]
+               [--bump-message BUMP_MESSAGE] [--prerelease {alpha,beta,rc}]
+               [--devrelease DEVRELEASE] [--increment {MAJOR,MINOR,PATCH}]
+               [--increment-mode {linear,exact}] [--check-consistency]
+               [--annotated-tag]
+               [--annotated-tag-message ANNOTATED_TAG_MESSAGE] [--gpg-sign]
+               [--changelog-to-stdout] [--git-output-to-stderr] [--retry]
+               [--major-version-zero] [--template TEMPLATE] [--extra EXTRA]
+               [--file-name FILE_NAME] [--prerelease-offset PRERELEASE_OFFSET]
+               [--version-scheme {pep440,semver,semver2}]
+               [--version-type {pep440,semver,semver2}]
+               [--build-metadata BUILD_METADATA]
+               [MANUAL_VERSION]
+
+bump semantic version based on the git log
+
+positional arguments:
+  MANUAL_VERSION        bump to the given version (e.g: 1.5.3)
+
+options:
+  -h, --help            show this help message and exit
+  --dry-run             show output to stdout, no commit, no modified files
+  --files-only          bump version in the files from the config
+  --local-version       bump only the local version portion
+  --changelog, -ch      generate the changelog for the newest version
+  --no-verify           this option bypasses the pre-commit and commit-msg
+                        hooks
+  --yes                 accept automatically questions done
+  --tag-format TAG_FORMAT
+                        the format used to tag the commit and read it, use it
+                        in existing projects, wrap around simple quotes
+  --bump-message BUMP_MESSAGE
+                        template used to create the release commit, useful
+                        when working with CI
+  --prerelease {alpha,beta,rc}, -pr {alpha,beta,rc}
+                        choose type of prerelease
+  --devrelease DEVRELEASE, -d DEVRELEASE
+                        specify non-negative integer for dev. release
+  --increment {MAJOR,MINOR,PATCH}
+                        manually specify the desired increment
+  --increment-mode {linear,exact}
+                        set the method by which the new version is chosen.
+                        'linear' (default) guesses the next version based on
+                        typical linear version progression, such that bumping
+                        of a pre-release with lower precedence than the
+                        current pre-release phase maintains the current phase
+                        of higher precedence. 'exact' applies the changes that
+                        have been specified (or determined from the commit
+                        log) without interpretation, such that the increment
+                        and pre-release are always honored
+  --check-consistency, -cc
+                        check consistency among versions defined in commitizen
+                        configuration and version_files
+  --annotated-tag, -at  create annotated tag instead of lightweight one
+  --annotated-tag-message ANNOTATED_TAG_MESSAGE, -atm ANNOTATED_TAG_MESSAGE
+                        create annotated tag message
+  --gpg-sign, -s        sign tag instead of lightweight one
+  --changelog-to-stdout
+                        Output changelog to the stdout
+  --git-output-to-stderr
+                        Redirect git output to stderr
+  --retry               retry commit if it fails the 1st time
+  --major-version-zero  keep major version at zero, even for breaking changes
+  --template TEMPLATE, -t TEMPLATE
+                        changelog template file name (relative to the current
+                        working directory)
+  --extra EXTRA, -e EXTRA
+                        a changelog extra variable (in the form 'key=value')
+  --file-name FILE_NAME
+                        file name of changelog (default: 'CHANGELOG.md')
+  --prerelease-offset PRERELEASE_OFFSET
+                        start pre-releases with this offset
+  --version-scheme {pep440,semver,semver2}
+                        choose version scheme
+  --version-type {pep440,semver,semver2}
+                        Deprecated, use --version-scheme
+  --build-metadata BUILD_METADATA
+                        Add additional build-metadata to the version-number

tests/commands/test_changelog_command.py

@@ -1637,3 +1637,15 @@ def test_export_changelog_template_from_plugin(
 
     assert target.exists()
     assert target.read_text() == tpl
+
+
+def test_changelog_command_shows_description_when_use_help_option(
+    mocker: MockFixture, capsys, file_regression
+):
+    testargs = ["cz", "changelog", "--help"]
+    mocker.patch.object(sys, "argv", testargs)
+    with pytest.raises(SystemExit):
+        cli.main()
+
+    out, _ = capsys.readouterr()
+    file_regression.check(out, extension=".txt")

tests/commands/test_changelog_command/test_changelog_command_shows_description_when_use_help_option.txt

@@ -0,0 +1,40 @@
+usage: cz changelog [-h] [--dry-run] [--file-name FILE_NAME]
+                    [--unreleased-version UNRELEASED_VERSION] [--incremental]
+                    [--start-rev START_REV] [--merge-prerelease]
+                    [--version-scheme {pep440,semver,semver2}]
+                    [--export-template EXPORT_TEMPLATE] [--template TEMPLATE]
+                    [--extra EXTRA]
+                    [rev_range]
+
+generate changelog (note that it will overwrite existing file)
+
+positional arguments:
+  rev_range             generates changelog for the given version (e.g: 1.5.3)
+                        or version range (e.g: 1.5.3..1.7.9)
+
+options:
+  -h, --help            show this help message and exit
+  --dry-run             show changelog to stdout
+  --file-name FILE_NAME
+                        file name of changelog (default: 'CHANGELOG.md')
+  --unreleased-version UNRELEASED_VERSION
+                        set the value for the new version (use the tag value),
+                        instead of using unreleased
+  --incremental         generates changelog from last created version, useful
+                        if the changelog has been manually modified
+  --start-rev START_REV
+                        start rev of the changelog. If not set, it will
+                        generate changelog from the start
+  --merge-prerelease    collect all changes from prereleases into next non-
+                        prerelease. If not set, it will include prereleases in
+                        the changelog
+  --version-scheme {pep440,semver,semver2}
+                        choose version scheme
+  --export-template EXPORT_TEMPLATE
+                        Export the changelog template into this file instead
+                        of rendering it
+  --template TEMPLATE, -t TEMPLATE
+                        changelog template file name (relative to the current
+                        working directory)
+  --extra EXTRA, -e EXTRA
+                        a changelog extra variable (in the form 'key=value')

tests/commands/test_check_command.py

@@ -414,3 +414,15 @@ def test_check_conventional_commit_succeed_with_git_diff(mocker, capsys):
     cli.main()
     out, _ = capsys.readouterr()
     assert "Commit validation: successful!" in out
+
+
+def test_check_command_shows_description_when_use_help_option(
+    mocker: MockFixture, capsys, file_regression
+):
+    testargs = ["cz", "check", "--help"]
+    mocker.patch.object(sys, "argv", testargs)
+    with pytest.raises(SystemExit):
+        cli.main()
+
+    out, _ = capsys.readouterr()
+    file_regression.check(out, extension=".txt")

tests/commands/test_check_command/test_check_command_shows_description_when_use_help_option.txt

@@ -0,0 +1,22 @@
+usage: cz check [-h]
+                [--commit-msg-file COMMIT_MSG_FILE | --rev-range REV_RANGE | -m MESSAGE]
+                [--allow-abort] [--allowed-prefixes [ALLOWED_PREFIXES ...]]
+
+validates that a commit message matches the commitizen schema
+
+options:
+  -h, --help            show this help message and exit
+  --commit-msg-file COMMIT_MSG_FILE
+                        ask for the name of the temporal file that contains
+                        the commit message. Using it in a git hook script:
+                        MSG_FILE=$1
+  --rev-range REV_RANGE
+                        a range of git rev to check. e.g, master..HEAD
+  -m MESSAGE, --message MESSAGE
+                        commit message that needs to be checked
+  --allow-abort         allow empty commit messages, which typically abort a
+                        commit
+  --allowed-prefixes [ALLOWED_PREFIXES ...]
+                        allowed commit message prefixes. If the message starts
+                        by one of these prefixes, the message won't be checked
+                        against the regex

tests/commands/test_commit_command.py

@@ -1,10 +1,11 @@
 import os
+import sys
 
 import pytest
 from pytest_mock import MockFixture
 from unittest.mock import ANY
 
-from commitizen import cmd, commands
+from commitizen import cli, cmd, commands
 from commitizen.cz.exceptions import CzException
 from commitizen.cz.utils import get_backup_file_path
 from commitizen.exceptions import (
@@ -406,3 +407,15 @@ def test_commit_command_with_message_length_limit(config, mocker: MockFixture):
 
     with pytest.raises(CommitMessageLengthExceededError):
         commands.Commit(config, {"message_length_limit": message_length - 1})()
+
+
+def test_commit_command_shows_description_when_use_help_option(
+    mocker: MockFixture, capsys, file_regression
+):
+    testargs = ["cz", "commit", "--help"]
+    mocker.patch.object(sys, "argv", testargs)
+    with pytest.raises(SystemExit):
+        cli.main()
+
+    out, _ = capsys.readouterr()
+    file_regression.check(out, extension=".txt")

tests/commands/test_commit_command/test_commit_command_shows_description_when_use_help_option.txt

@@ -0,0 +1,20 @@
+usage: cz commit [-h] [--retry] [--no-retry] [--dry-run]
+                 [--write-message-to-file FILE_PATH] [-s] [-a]
+                 [-l MESSAGE_LENGTH_LIMIT]
+
+create new commit
+
+options:
+  -h, --help            show this help message and exit
+  --retry               retry last commit
+  --no-retry            skip retry if retry_after_failure is set to true
+  --dry-run             show output to stdout, no commit, no modified files
+  --write-message-to-file FILE_PATH
+                        write message to file before committing (can be
+                        combined with --dry-run)
+  -s, --signoff         sign off the commit
+  -a, --all             Tell the command to automatically stage files that
+                        have been modified and deleted, but new files you have
+                        not told Git about are not affected.
+  -l MESSAGE_LENGTH_LIMIT, --message-length-limit MESSAGE_LENGTH_LIMIT
+                        length limit of the commit message; 0 for no limit

tests/commands/test_example_command.py

@@ -0,0 +1,17 @@
+import pytest
+import sys
+from commitizen import cli
+
+from pytest_mock import MockerFixture
+
+
+def test_example_command_shows_description_when_use_help_option(
+    mocker: MockerFixture, capsys, file_regression
+):
+    testargs = ["cz", "example", "--help"]
+    mocker.patch.object(sys, "argv", testargs)
+    with pytest.raises(SystemExit):
+        cli.main()
+
+    out, _ = capsys.readouterr()
+    file_regression.check(out, extension=".txt")

tests/commands/test_example_command/test_example_command_shows_description_when_use_help_option.txt

@@ -0,0 +1,6 @@
+usage: cz example [-h]
+
+show commit example
+
+options:
+  -h, --help  show this help message and exit

tests/commands/test_info_command.py

@@ -0,0 +1,17 @@
+import pytest
+import sys
+from commitizen import cli
+
+from pytest_mock import MockerFixture
+
+
+def test_info_command_shows_description_when_use_help_option(
+    mocker: MockerFixture, capsys, file_regression
+):
+    testargs = ["cz", "info", "--help"]
+    mocker.patch.object(sys, "argv", testargs)
+    with pytest.raises(SystemExit):
+        cli.main()
+
+    out, _ = capsys.readouterr()
+    file_regression.check(out, extension=".txt")

tests/commands/test_info_command/test_info_command_shows_description_when_use_help_option.txt

@@ -0,0 +1,6 @@
+usage: cz info [-h]
+
+show information about the cz
+
+options:
+  -h, --help  show this help message and exit

tests/commands/test_init_command.py

@@ -2,13 +2,14 @@
 
 import json
 import os
+import sys
 from typing import Any
 
 import pytest
 import yaml
 from pytest_mock import MockFixture
 
-from commitizen import commands
+from commitizen import cli, commands
 from commitizen.__version__ import __version__
 from commitizen.exceptions import InitFailedError, NoAnswersError
 
@@ -251,3 +252,15 @@ def test_pre_commit_exec_failed(
         with tmpdir.as_cwd():
             with pytest.raises(InitFailedError):
                 commands.Init(config)()
+
+
+def test_init_command_shows_description_when_use_help_option(
+    mocker: MockFixture, capsys, file_regression
+):
+    testargs = ["cz", "init", "--help"]
+    mocker.patch.object(sys, "argv", testargs)
+    with pytest.raises(SystemExit):
+        cli.main()
+
+    out, _ = capsys.readouterr()
+    file_regression.check(out, extension=".txt")