diff --git a/README.md b/README.md
index 64ba00c1..c772e9b3 100644
--- a/README.md
+++ b/README.md
@@ -270,13 +270,18 @@ repos:
### Shell completion
-You can generate a shell completion script with `reuse --print-completion bash`.
-Replace 'bash' as needed. You must place the printed text in a file dictated by
-your shell to benefit from completions.
+In order to enable shell completion, you need to generate the shell completion
+script. You do this with `_REUSE_COMPLETE=bash_source reuse`. Replace `bash`
+with `zsh` or `fish` as needed, or any other shells supported by the
+Python`click` library. You can then source the output in your shell rc file,
+like so (e.g.`~/.bashrc`):
-This functionality depends on `shtab`, which is an optional dependency. To
-benefit from this feature, install reuse with the `completion` extra, like
-`pipx install reuse[completion]`.
+```bash
+eval "$(_REUSE__COMPLETE=bash_source reuse)"
+```
+
+Alternatively, you can place the generated completion script in
+`${XDG_DATA_HOME}/bash-completion/completions/reuse`.
## Maintainers
diff --git a/changelog.d/changed/click.md b/changelog.d/changed/click.md
index fcb9830c..bedc5e5a 100644
--- a/changelog.d/changed/click.md
+++ b/changelog.d/changed/click.md
@@ -1,3 +1,17 @@
- Switched from `argparse` to `click` for handling the CLI. The CLI should still
- handle identically, with identical options and arguments, but some stuff
- changed under the hood. (#1084)
+ handle the same, with identical options and arguments, but some stuff changed
+ under the hood. (#1084)
+
+ Find here a small list of differences:
+
+ - `-h` is no longer shorthand for `--help`.
+ - `--version` now outputs "reuse, version X.Y.Z", followed by a licensing
+ blurb on different paragraphs.
+ - Some options are made explicitly mutually exclusive, such as `annotate`'s
+ `--skip-unrecognised` and `--style`, and `download`'s `--output` and
+ `--all`.
+ - Subcommands which take a list of things (files, license) as arguments, such
+ as `annotate`, `lint-file`, or `download`, now also allow zero arguments.
+ This will do nothing, but can be useful in scripting.
+ - `annotate` and `lint-file` now also take directories as arguments. This will
+ do nothing, but can be useful in scripting.
diff --git a/docs/man/reuse-annotate.rst b/docs/man/reuse-annotate.rst
index ae01e0af..9a1795cb 100644
--- a/docs/man/reuse-annotate.rst
+++ b/docs/man/reuse-annotate.rst
@@ -46,22 +46,22 @@ Mandatory options
-----------------
At least *one* among the following options is required. They contain the
-information which the tool will add to the file(s).
+information which the tool will add to the file(s). You can repeat these
+options.
.. option:: -c, --copyright COPYRIGHT
A copyright holder. This does not contain the year or the copyright prefix.
See :option:`--year` and :option:`--copyright-prefix` for the year and prefix.
- This option can be repeated.
.. option:: -l, --license LICENSE
- An SPDX license identifier. This option can be repeated.
+ An SPDX license identifier.
.. option:: --contributor CONTRIBUTOR
A name of a contributor. The contributor will be added via the
- ``SPDX-FileContributor:`` tag. This option can be repeated.
+ ``SPDX-FileContributor:`` tag.
Other options
-------------
@@ -143,7 +143,7 @@ Other options
Instead of aborting when a file extension does not have an associated comment
style, skip those files.
-.. option:: -h, --help
+.. option:: --help
Display help and exit.
diff --git a/docs/man/reuse-convert-dep5.rst b/docs/man/reuse-convert-dep5.rst
index 427344c2..0be35935 100644
--- a/docs/man/reuse-convert-dep5.rst
+++ b/docs/man/reuse-convert-dep5.rst
@@ -21,7 +21,7 @@ functionally equivalent ``REUSE.toml`` file in the root of the project. The
Options
-------
-.. option:: -h, --help
+.. option:: --help
Display help and exit.
diff --git a/docs/man/reuse-download.rst b/docs/man/reuse-download.rst
index 4c79f0fa..88adc424 100644
--- a/docs/man/reuse-download.rst
+++ b/docs/man/reuse-download.rst
@@ -36,11 +36,11 @@ Options
If downloading a single file, output it to a specific file instead of putting
it in a detected ``LICENSES/`` directory.
-.. option:: --source SOURCE
+.. option:: --source PATH
Specify a source from which to copy custom ``LicenseRef-`` files. This can be
a directory containing such file, or a path to the file itself.
-.. option:: -h, --help
+.. option:: --help
Display help and exit.
diff --git a/docs/man/reuse-lint-file.rst b/docs/man/reuse-lint-file.rst
index 314cc46d..8e9487cb 100644
--- a/docs/man/reuse-lint-file.rst
+++ b/docs/man/reuse-lint-file.rst
@@ -45,6 +45,6 @@ Options
Output one line per error, prefixed by the file path. This option is the
default.
-.. option:: -h, --help
+.. option:: --help
Display help and exit.
diff --git a/docs/man/reuse-lint.rst b/docs/man/reuse-lint.rst
index 6c0cf6d7..03c66c2d 100644
--- a/docs/man/reuse-lint.rst
+++ b/docs/man/reuse-lint.rst
@@ -97,6 +97,6 @@ Options
Output one line per error, prefixed by the file path.
-.. option:: -h, --help
+.. option:: --help
Display help and exit.
diff --git a/docs/man/reuse-spdx.rst b/docs/man/reuse-spdx.rst
index 46515dce..e6d5fb4e 100644
--- a/docs/man/reuse-spdx.rst
+++ b/docs/man/reuse-spdx.rst
@@ -41,6 +41,6 @@ Options
Name of the creator (organization) of the bill of materials.
-.. option:: -h, --help
+.. option:: --help
Display help and exit.
diff --git a/docs/man/reuse-supported-licenses.rst b/docs/man/reuse-supported-licenses.rst
index 8dbb8759..902d171f 100644
--- a/docs/man/reuse-supported-licenses.rst
+++ b/docs/man/reuse-supported-licenses.rst
@@ -25,6 +25,6 @@ full name of the license, and an URL to the license.
Options
-------
-.. option:: -h, --help
+.. option:: --help
Display help and exit.
diff --git a/docs/man/reuse.rst b/docs/man/reuse.rst
index 121b6614..e1b448c2 100644
--- a/docs/man/reuse.rst
+++ b/docs/man/reuse.rst
@@ -78,18 +78,7 @@ Options
current working directory's VCS repository, or to the current working
directory.
-.. option:: -s, --print-completion SHELL
-
- Print a static shell completion script for the given shell and exit. You must
- place the printed text in a file dictated by your shell before the completions
- will function. For Bash, this file is
- ``${XDG_DATA_HOME}/bash-completion/reuse``.
-
- This option depends on ``shtab``, which is an optional dependency of
- :program:`reuse`. The supported shells depend on your installed version of
- ``shtab``.
-
-.. option:: -h, --help
+.. option:: --help
Display help and exit. If no command is provided, this option is implied.
@@ -112,6 +101,9 @@ Commands
:manpage:`reuse-lint(1)`
Verify whether a project is compliant with the REUSE Specification.
+:manpage:`reuse-lint-file(1)`
+ Verify whether individual files are compliant with the REUSE Specification.
+
:manpage:`reuse-spdx(1)`
Generate SPDX bill of materials.
diff --git a/src/reuse/cli/annotate.py b/src/reuse/cli/annotate.py
index f32fc9b3..3ba231ee 100644
--- a/src/reuse/cli/annotate.py
+++ b/src/reuse/cli/annotate.py
@@ -121,8 +121,9 @@ def verify_paths_comment_style(
"{}\n\n{}".format(
_(
"The following files do not have a recognised file"
- " extension. Please use --style, --force-dot-license,"
- " --fallback-dot-license, or --skip-unrecognised:"
+ " extension. Please use '--style',"
+ " '--force-dot-license', '--fallback-dot-license', or"
+ " '--skip-unrecognised':"
),
"\n".join(str(path) for path in unrecognised_files),
)
@@ -153,14 +154,14 @@ def verify_paths_line_handling(
raise click.UsageError(
_(
"'{path}' does not support single-line comments, please"
- " do not use --single-line"
+ " do not use '--single-line'."
).format(path=path)
)
if multi_line and not style.can_handle_multi():
raise click.UsageError(
_(
"'{path}' does not support multi-line comments, please"
- " do not use --multi-line"
+ " do not use '--multi-line'."
).format(path=path)
)
@@ -268,7 +269,7 @@ def get_reuse_info(
]
_HELP = (
- _("Add copyright and licensing into the header of one or more" " files.")
+ _("Add copyright and licensing into the headers of files.")
+ "\n\n"
+ _(
"By using --copyright and --license, you can specify which"
@@ -290,9 +291,10 @@ def get_reuse_info(
"--copyright",
"-c",
"copyrights",
+ metavar=_("COPYRIGHT"),
type=str,
multiple=True,
- help=_("Copyright statement."),
+ help=_("Copyright statement, repeatable."),
)
@click.option(
"--license",
@@ -301,21 +303,24 @@ def get_reuse_info(
metavar=_("SPDX_IDENTIFIER"),
type=spdx_identifier,
multiple=True,
- help=_("SPDX License Identifier."),
+ help=_("SPDX License Identifier, repeatable."),
)
@click.option(
"--contributor",
"contributors",
+ metavar=_("CONTRIBUTOR"),
type=str,
multiple=True,
- help=_("File contributor."),
+ help=_("File contributor, repeatable."),
)
@click.option(
"--year",
"-y",
"years",
+ metavar=_("YEAR"),
cls=MutexOption,
mutually_exclusive=_YEAR_MUTEX,
+ # TODO: This multiple behaviour is kind of word. Let's redo it.
multiple=True,
type=str,
help=_("Year of copyright statement."),
@@ -342,6 +347,7 @@ def get_reuse_info(
"--template",
"-t",
"template_str",
+ metavar=_("TEMPLATE"),
type=str,
help=_("Name of template to use."),
)
diff --git a/src/reuse/cli/convert_dep5.py b/src/reuse/cli/convert_dep5.py
index f213bc33..c7bec026 100644
--- a/src/reuse/cli/convert_dep5.py
+++ b/src/reuse/cli/convert_dep5.py
@@ -30,7 +30,7 @@ def convert_dep5(obj: ClickObj) -> None:
# pylint: disable=missing-function-docstring
project = cast(Project, obj.project)
if not (project.root / ".reuse/dep5").exists():
- raise click.UsageError(_("no '.reuse/dep5' file"))
+ raise click.UsageError(_("No '.reuse/dep5' file."))
text = toml_from_dep5(
cast(ReuseDep5, project.global_licensing).dep5_copyright
diff --git a/src/reuse/cli/download.py b/src/reuse/cli/download.py
index a1d57b91..55d3998a 100644
--- a/src/reuse/cli/download.py
+++ b/src/reuse/cli/download.py
@@ -136,7 +136,7 @@ def _successfully_downloaded(destination: StrPath) -> None:
type=click.Path(exists=True, readable=True, path_type=Path),
help=_(
"Source from which to copy custom LicenseRef- licenses, either"
- " a directory that contains the file or the file itself"
+ " a directory that contains the file or the file itself."
),
)
@click.argument(
diff --git a/src/reuse/cli/lint.py b/src/reuse/cli/lint.py
index f4545081..0509ce0d 100644
--- a/src/reuse/cli/lint.py
+++ b/src/reuse/cli/lint.py
@@ -14,6 +14,7 @@
import click
+from .. import __REUSE_version__
from ..i18n import _
from ..lint import format_json, format_lines, format_plain
from ..project import Project
@@ -25,11 +26,11 @@
_HELP = (
_(
- "Lint the project directory for compliance with"
- " version {reuse_version} of the REUSE Specification. You can"
- " find the latest version of the specification at"
- " ."
- )
+ "Lint the project directory for REUSE compliance. This version of the"
+ " tool checks against version {reuse_version} of the REUSE"
+ " Specification. You can find the latest version of the specification"
+ " at ."
+ ).format(reuse_version=__REUSE_version__)
+ "\n\n"
+ _("Specifically, the following criteria are checked:")
+ "\n\n"
diff --git a/src/reuse/cli/lint_file.py b/src/reuse/cli/lint_file.py
index 7de7d83e..b6e8bd81 100644
--- a/src/reuse/cli/lint_file.py
+++ b/src/reuse/cli/lint_file.py
@@ -23,9 +23,9 @@
_OUTPUT_MUTEX = ["quiet", "lines"]
_HELP = _(
- "Lint individual files. The specified FILEs are checked for the presence"
- " of copyright and licensing information, and whether the found licenses"
- " are included in the LICENSES/ directory."
+ "Lint individual files for REUSE compliance. The specified FILEs are"
+ " checked for the presence of copyright and licensing information, and"
+ " whether the found licenses are included in the LICENSES/ directory."
)
@@ -63,7 +63,7 @@ def lint_file(
for file_ in subset_files:
if not file_.resolve().is_relative_to(project.root.resolve()):
raise click.UsageError(
- _("'{file}' is not inside of '{root}'").format(
+ _("'{file}' is not inside of '{root}'.").format(
file=file_, root=project.root
)
)
diff --git a/src/reuse/cli/main.py b/src/reuse/cli/main.py
index b2e2a955..e8524890 100644
--- a/src/reuse/cli/main.py
+++ b/src/reuse/cli/main.py
@@ -45,6 +45,7 @@
" the Free Software Foundation, either version 3 of the License, or"
" (at your option) any later version."
)
+ + "\n\n"
+ _(
"This program is distributed in the hope that it will be useful,"
" but WITHOUT ANY WARRANTY; without even the implied warranty of"
diff --git a/src/reuse/cli/spdx.py b/src/reuse/cli/spdx.py
index 115dd25d..9c69477b 100644
--- a/src/reuse/cli/spdx.py
+++ b/src/reuse/cli/spdx.py
@@ -81,8 +81,8 @@ def spdx(
):
raise click.UsageError(
_(
- "--creator-person=NAME or --creator-organization=NAME"
- " required when --add-license-concluded is provided"
+ "'--creator-person' or '--creator-organization'"
+ " is required when '--add-license-concluded' is provided."
)
)