From e6f7aa395fabc7eca1ee4d93e454d2551cea505c Mon Sep 17 00:00:00 2001
From: Jelle van der Waa <jelle@archlinux.org>
Date: Sun, 5 Nov 2023 16:11:12 +0100
Subject: feat(version): introduce version check subcommand

The version subcommand handles pkgver related commands, the first
subcommand being `check`. Check runs nvchecker if a `.nvchecker.toml`
file exists and compares the current pkgver with the latest release.

Introduces nvchecker as optional dependency which has to be installed in
order to use this particular subcommand.

BREAKING CHANGE: formerly pkgctl version would output the version of the
pkgctl tool, now it is used as a version related subcommand.

Fixes #140

Component: pkgctl version
Component: pkgctl version check
Co-authored-by: Christian Heusel <christian@heusel.eu>
---
 doc/man/pkgctl-version-check.1.asciidoc | 35 +++++++++++++++++++++++++++++++++
 1 file changed, 35 insertions(+)
 create mode 100644 doc/man/pkgctl-version-check.1.asciidoc

(limited to 'doc/man/pkgctl-version-check.1.asciidoc')

diff --git a/doc/man/pkgctl-version-check.1.asciidoc b/doc/man/pkgctl-version-check.1.asciidoc
new file mode 100644
index 0000000..97d8c47
--- /dev/null
+++ b/doc/man/pkgctl-version-check.1.asciidoc
@@ -0,0 +1,35 @@
+pkgctl-version-check(1)
+=======================
+
+Name
+----
+pkgctl-version-check - Check if there is an new upstream version available
+
+Synopsis
+--------
+pkgctl version check [OPTIONS] [PKGBASE...]
+
+Description
+-----------
+
+Uses nvchecker, a .nvchecker.toml file and the version specified in the current
+PKGBUILDs pkgver to check if there is a newer package version available to
+which this package could possibly be upgraded.
+
+The current working directory is used if no PKGBASE is specified.
+
+See the section on configuration files in **nvchecker**(1) for possible options
+which can be utilized in .nvchecker.toml.
+
+Options
+-------
+
+*-h, --help*::
+	Show a help text
+
+See Also
+--------
+
+linkman:nvchecker[1]
+
+include::include/footer.asciidoc[]
-- 
cgit v1.2.3-54-g00ecf


From 96f39525bf60a499aa840015159d9040b53be69a Mon Sep 17 00:00:00 2001
From: Levente Polyak <anthraxx@archlinux.org>
Date: Sat, 13 Jan 2024 15:27:34 +0100
Subject: feat(version): support nvchecker keyfile from user config home

This adds support for global keyfile from the user config home
XDG_CONFIG_HOME which allows to set tokens for GitHub and GitLab for
certain nvchecker configuration.

When ~/.config/nvchecker/keyfile.toml exists, it will automatically be
appended as keyfile of the local .nvchecker.toml file.

Component: pkgctl version check
Signed-off-by: Levente Polyak <anthraxx@archlinux.org>
---
 doc/man/pkgctl-version-check.1.asciidoc |  8 +++++++-
 src/lib/version/check.sh                | 12 +++++++++++-
 2 files changed, 18 insertions(+), 2 deletions(-)

(limited to 'doc/man/pkgctl-version-check.1.asciidoc')

diff --git a/doc/man/pkgctl-version-check.1.asciidoc b/doc/man/pkgctl-version-check.1.asciidoc
index 97d8c47..ed9abdf 100644
--- a/doc/man/pkgctl-version-check.1.asciidoc
+++ b/doc/man/pkgctl-version-check.1.asciidoc
@@ -18,7 +18,13 @@ which this package could possibly be upgraded.
 
 The current working directory is used if no PKGBASE is specified.
 
-See the section on configuration files in **nvchecker**(1) for possible options
+Configuration
+-------------
+
+To provide GitHub or GitLab tokens to nvchecker, a `keyfile.toml` will be
+supplied from `$XDG_CONFIG_HOME`/nvchecker.
+
+See the section on configuration files in linkman:nvchecker[1] for possible options
 which can be utilized in .nvchecker.toml.
 
 Options
diff --git a/src/lib/version/check.sh b/src/lib/version/check.sh
index c78e364..600a346 100644
--- a/src/lib/version/check.sh
+++ b/src/lib/version/check.sh
@@ -23,6 +23,9 @@ pkgctl_version_check_usage() {
 
 		The current working directory is used if no PKGBASE is specified.
 
+		To provide GitHub or GitLab tokens to nvchecker, a keyfile.toml
+		will be supplied from \${XDG_CONFIG_HOME}/nvchecker.
+
 		OPTIONS
 		    -h, --help          Show this help text
 
@@ -110,6 +113,8 @@ get_upstream_version() {
 	local config=.nvchecker.toml
 	local output errors upstream_version
 	local output
+	local opts=()
+	local keyfile="${XDG_CONFIG_HOME:-${HOME}/.config}/nvchecker/keyfile.toml"
 
 	# check nvchecker config file
 	if ! errors=$(nvchecker_check_config "${config}"); then
@@ -117,7 +122,12 @@ get_upstream_version() {
 		return 1
 	fi
 
-	if ! output=$(nvchecker --file "${config}" --logger json 2>&1 | \
+	# populate keyfile to nvchecker opts
+	if [[ -f ${keyfile} ]]; then
+		opts+=(--keyfile "${keyfile}")
+	fi
+
+	if ! output=$(nvchecker --file "${config}" --logger json "${opts[@]}" 2>&1 | \
 			jq --raw-output 'select(.level != "debug")'); then
 		printf "failed to run nvchecker: %s" "${output}"
 		return 1
-- 
cgit v1.2.3-54-g00ecf


From b258bb3b7c55d06bad108400450acd32cff05366 Mon Sep 17 00:00:00 2001
From: Levente Polyak <anthraxx@archlinux.org>
Date: Thu, 18 Jan 2024 03:33:13 +0100
Subject: feat(version): add verbose option to display up-to-date versions

Sometimes it can be desired to get a results for each entry even if the
current version is up-to-date. Add a --verbose option to print this
optional detail.

Component: pkgctl version check
Component: pkgctl version upgrade
Signed-off-by: Levente Polyak <anthraxx@archlinux.org>
---
 contrib/completion/bash/devtools.in       |  2 ++
 contrib/completion/zsh/_devtools.in       |  2 ++
 doc/man/pkgctl-version-check.1.asciidoc   |  3 +++
 doc/man/pkgctl-version-upgrade.1.asciidoc |  3 +++
 src/lib/version/check.sh                  | 25 ++++++++++++++++++++++---
 src/lib/version/upgrade.sh                | 21 ++++++++++++++++++++-
 6 files changed, 52 insertions(+), 4 deletions(-)

(limited to 'doc/man/pkgctl-version-check.1.asciidoc')

diff --git a/contrib/completion/bash/devtools.in b/contrib/completion/bash/devtools.in
index 101bd78..f8b1c9f 100644
--- a/contrib/completion/bash/devtools.in
+++ b/contrib/completion/bash/devtools.in
@@ -343,12 +343,14 @@ _pkgctl_version_cmds=(
 )
 
 _pkgctl_version_check_args=(
+	-v --verbose
 	-h --help
 )
 
 _pkgctl_version_check_opts() { _filedir -d; }
 
 _pkgctl_version_upgrade_args=(
+	-v --verbose
 	-h --help
 )
 
diff --git a/contrib/completion/zsh/_devtools.in b/contrib/completion/zsh/_devtools.in
index 38bf582..b427d20 100644
--- a/contrib/completion/zsh/_devtools.in
+++ b/contrib/completion/zsh/_devtools.in
@@ -292,11 +292,13 @@ _pkgctl_version_cmds=(
 )
 
 _pkgctl_version_check_args=(
+	'(-v --verbose)'{-v,--verbose}'[Display results including up-to-date versions]'
 	'(-h --help)'{-h,--help}'[Display usage]'
 	'*:git_dir:_files -/'
 )
 
 _pkgctl_version_upgrade_args=(
+	'(-v --verbose)'{-v,--verbose}'[Display results including up-to-date versions]'
 	'(-h --help)'{-h,--help}'[Display usage]'
 	'*:git_dir:_files -/'
 )
diff --git a/doc/man/pkgctl-version-check.1.asciidoc b/doc/man/pkgctl-version-check.1.asciidoc
index ed9abdf..3113afa 100644
--- a/doc/man/pkgctl-version-check.1.asciidoc
+++ b/doc/man/pkgctl-version-check.1.asciidoc
@@ -30,6 +30,9 @@ which can be utilized in .nvchecker.toml.
 Options
 -------
 
+*-v, --verbose*::
+	Display results including up-to-date versions
+
 *-h, --help*::
 	Show a help text
 
diff --git a/doc/man/pkgctl-version-upgrade.1.asciidoc b/doc/man/pkgctl-version-upgrade.1.asciidoc
index 3d5d882..7f9cd96 100644
--- a/doc/man/pkgctl-version-upgrade.1.asciidoc
+++ b/doc/man/pkgctl-version-upgrade.1.asciidoc
@@ -22,6 +22,9 @@ The current working directory is used if no PKGBASE is specified.
 Options
 -------
 
+*-v, --verbose*::
+	Display results including up-to-date versions
+
 *-h, --help*::
 	Show a help text
 
diff --git a/src/lib/version/check.sh b/src/lib/version/check.sh
index fba2d1a..9bc29c1 100644
--- a/src/lib/version/check.sh
+++ b/src/lib/version/check.sh
@@ -29,7 +29,8 @@ pkgctl_version_check_usage() {
 		will be supplied from \${XDG_CONFIG_HOME}/nvchecker.
 
 		OPTIONS
-		    -h, --help          Show this help text
+		    -v, --verbose    Display results including up-to-date versions
+		    -h, --help       Show this help text
 
 		EXAMPLES
 		    $ ${COMMAND} neovim vim
@@ -37,9 +38,10 @@ _EOF_
 }
 
 pkgctl_version_check() {
-	local path
 	local pkgbases=()
-	local status_file path pkgbase upstream_version result
+	local verbose=0
+
+	local path status_file path pkgbase upstream_version result
 
 	local up_to_date=()
 	local out_of_date=()
@@ -53,6 +55,10 @@ pkgctl_version_check() {
 				pkgctl_version_check_usage
 				exit 0
 				;;
+			-v|--verbose)
+				verbose=1
+				shift
+				;;
 			--)
 				shift
 				break
@@ -81,6 +87,11 @@ pkgctl_version_check() {
 		fi
 	fi
 
+	# enable verbose mode when we only have a single item to check
+	if (( ${#pkgbases[@]} == 1 )); then
+		verbose=1
+	fi
+
 	# start a terminal spinner as checking versions takes time
 	status_dir=$(mktemp --tmpdir="${WORKDIR}" --directory pkgctl-version-check-spinner.XXXXXXXXXX)
 	term_spinner_start "${status_dir}"
@@ -140,6 +151,14 @@ pkgctl_version_check() {
 	# stop the terminal spinner after all checks
 	term_spinner_stop "${status_dir}"
 
+	if (( verbose )) && (( ${#up_to_date[@]} > 0 )); then
+		printf "%sUp-to-date%s\n" "${section_separator}${BOLD}${UNDERLINE}" "${ALL_OFF}"
+		section_separator=$'\n'
+		for result in "${up_to_date[@]}"; do
+			msg_success " ${result}"
+		done
+	fi
+
 	if (( ${#failure[@]} > 0 )); then
 		printf "%sFailure%s\n" "${section_separator}${BOLD}${UNDERLINE}" "${ALL_OFF}"
 		section_separator=$'\n'
diff --git a/src/lib/version/upgrade.sh b/src/lib/version/upgrade.sh
index 9f884d0..70513ce 100644
--- a/src/lib/version/upgrade.sh
+++ b/src/lib/version/upgrade.sh
@@ -32,7 +32,8 @@ pkgctl_version_upgrade_usage() {
 		The current working directory is used if no PKGBASE is specified.
 
 		OPTIONS
-		    -h, --help          Show this help text
+		    -v, --verbose    Display results including up-to-date versions
+		    -h, --help       Show this help text
 
 		EXAMPLES
 		    $ ${COMMAND} neovim vim
@@ -42,6 +43,7 @@ _EOF_
 pkgctl_version_upgrade() {
 	local path upstream_version result
 	local pkgbases=()
+	local verbose=0
 	local exit_code=0
 	local current_item=0
 
@@ -51,6 +53,10 @@ pkgctl_version_upgrade() {
 				pkgctl_version_upgrade_usage
 				exit 0
 				;;
+			-v|--verbose)
+				verbose=1
+				shift
+				;;
 			--)
 				shift
 				break
@@ -79,6 +85,11 @@ pkgctl_version_upgrade() {
 		fi
 	fi
 
+	# enable verbose mode when we only have a single item to check
+	if (( ${#pkgbases[@]} == 1 )); then
+		verbose=1
+	fi
+
 	# start a terminal spinner as checking versions takes time
 	status_dir=$(mktemp --tmpdir="${WORKDIR}" --directory pkgctl-version-check-spinner.XXXXXXXXXX)
 	term_spinner_start "${status_dir}"
@@ -142,6 +153,14 @@ pkgctl_version_upgrade() {
 	# stop the terminal spinner after all checks
 	term_spinner_stop "${status_dir}"
 
+	if (( verbose )) && (( ${#up_to_date[@]} > 0 )); then
+		printf "%sUp-to-date%s\n" "${section_separator}${BOLD}${UNDERLINE}" "${ALL_OFF}"
+		section_separator=$'\n'
+		for result in "${up_to_date[@]}"; do
+			msg_success " ${result}"
+		done
+	fi
+
 	if (( ${#failure[@]} > 0 )); then
 		exit_code=1
 		printf "%sFailure%s\n" "${section_separator}${BOLD}${UNDERLINE}" "${ALL_OFF}"
-- 
cgit v1.2.3-54-g00ecf


From e3edf25554c78e28679b100e24c55c87ee65a22d Mon Sep 17 00:00:00 2001
From: Levente Polyak <anthraxx@archlinux.org>
Date: Thu, 18 Jan 2024 19:15:22 +0100
Subject: feat(version): use exit code for check to indicate out-of-date
 versions

It can be handy to have an exit code that allows better status
indication or chaining.

On exit, return one of the following codes:

- 0: Normal exit condition, all checked versions are up-to-date
- 1: Unknown cause of failure
- 2: Normal exit condition, but there are out-of-date versions
- 3: Failed to run some version checks

Component: pkgctl version check
Signed-off-by: Levente Polyak <anthraxx@archlinux.org>
---
 doc/man/pkgctl-version-check.1.asciidoc | 17 +++++++++++++++++
 src/lib/version.sh                      |  4 ++--
 src/lib/version/check.sh                | 14 ++++++++++++++
 3 files changed, 33 insertions(+), 2 deletions(-)

(limited to 'doc/man/pkgctl-version-check.1.asciidoc')

diff --git a/doc/man/pkgctl-version-check.1.asciidoc b/doc/man/pkgctl-version-check.1.asciidoc
index 3113afa..fa5401f 100644
--- a/doc/man/pkgctl-version-check.1.asciidoc
+++ b/doc/man/pkgctl-version-check.1.asciidoc
@@ -36,6 +36,23 @@ Options
 *-h, --help*::
 	Show a help text
 
+Errors
+------
+
+On exit, return one of the following codes:
+
+*0*::
+	Normal exit condition, all checked versions are up-to-date
+
+*1*::
+	Unknown cause of failure
+
+*2*::
+	Normal exit condition, but there are out-of-date versions
+
+*3*::
+	Failed to run some version checks
+
 See Also
 --------
 
diff --git a/src/lib/version.sh b/src/lib/version.sh
index 14cd810..4340fca 100644
--- a/src/lib/version.sh
+++ b/src/lib/version.sh
@@ -47,7 +47,7 @@ pkgctl_version() {
 				# shellcheck source=src/lib/version/check.sh
 				source "${_DEVTOOLS_LIBRARY_DIR}"/lib/version/check.sh
 				pkgctl_version_check "$@"
-				exit 0
+				exit $?
 				;;
 			upgrade)
 				_DEVTOOLS_COMMAND+=" $1"
@@ -55,7 +55,7 @@ pkgctl_version() {
 				# shellcheck source=src/lib/version/upgrade.sh
 				source "${_DEVTOOLS_LIBRARY_DIR}"/lib/version/upgrade.sh
 				pkgctl_version_upgrade "$@"
-				exit 0
+				exit $?
 				;;
 			*)
 				die "invalid argument: %s" "$1"
diff --git a/src/lib/version/check.sh b/src/lib/version/check.sh
index 9bc29c1..cc8827d 100644
--- a/src/lib/version/check.sh
+++ b/src/lib/version/check.sh
@@ -15,6 +15,14 @@ source /usr/share/makepkg/util/message.sh
 
 set -eo pipefail
 
+readonly PKGCTL_VERSION_CHECK_EXIT_UP_TO_DATE=0
+export PKGCTL_VERSION_CHECK_EXIT_UP_TO_DATE
+readonly PKGCTL_VERSION_CHECK_EXIT_OUT_OF_DATE=2
+export PKGCTL_VERSION_CHECK_EXIT_OUT_OF_DATE
+readonly PKGCTL_VERSION_CHECK_EXIT_FAILURE=3
+export PKGCTL_VERSION_CHECK_EXIT_FAILURE
+
+
 pkgctl_version_check_usage() {
 	local -r COMMAND=${_DEVTOOLS_COMMAND:-${BASH_SOURCE[0]##*/}}
 	cat <<- _EOF_
@@ -48,6 +56,7 @@ pkgctl_version_check() {
 	local failure=()
 	local current_item=0
 	local section_separator=''
+	local exit_code=${PKGCTL_VERSION_CHECK_EXIT_UP_TO_DATE}
 
 	while (( $# )); do
 		case $1 in
@@ -160,6 +169,7 @@ pkgctl_version_check() {
 	fi
 
 	if (( ${#failure[@]} > 0 )); then
+		exit_code=${PKGCTL_VERSION_CHECK_EXIT_FAILURE}
 		printf "%sFailure%s\n" "${section_separator}${BOLD}${UNDERLINE}" "${ALL_OFF}"
 		section_separator=$'\n'
 		for result in "${failure[@]}"; do
@@ -168,6 +178,7 @@ pkgctl_version_check() {
 	fi
 
 	if (( ${#out_of_date[@]} > 0 )); then
+		exit_code=${PKGCTL_VERSION_CHECK_EXIT_OUT_OF_DATE}
 		printf "%sOut-of-date%s\n" "${section_separator}${BOLD}${UNDERLINE}" "${ALL_OFF}"
 		section_separator=$'\n'
 		for result in "${out_of_date[@]}"; do
@@ -183,6 +194,9 @@ pkgctl_version_check() {
 			"${#out_of_date[@]}" \
 			"${#failure[@]}"
 	fi
+
+	# return status based on results
+	return "${exit_code}"
 }
 
 get_upstream_version() {
-- 
cgit v1.2.3-54-g00ecf


From 4d72f4560c3a64b38dcdb705ec633c3c2ba1f20c Mon Sep 17 00:00:00 2001
From: Levente Polyak <anthraxx@archlinux.org>
Date: Fri, 19 Jan 2024 01:57:18 +0100
Subject: doc(version): extensively revamp documentation for version
 subcommands

Enhanced and overhauled the documentation for the 'version' subcommand.
The improvements include comprehensive details on the subcommand's
behavior, usage, and a variety of scenarios it handles.

Added a central section within the pkgctl-version manpage that documents
the nvchecker configuration and rules.

Component: pkgctl version
Singled-off-by: Levente Polyak <anthraxx@archlinux.org>
---
 contrib/completion/zsh/_devtools.in       |  6 +++---
 doc/man/pkgctl-version-check.1.asciidoc   | 29 +++++++++++++++++------------
 doc/man/pkgctl-version-upgrade.1.asciidoc | 24 +++++++++++++++++++-----
 doc/man/pkgctl-version.1.asciidoc         | 29 +++++++++++++++++++++++++----
 doc/man/pkgctl.1.asciidoc                 |  2 +-
 src/lib/version.sh                        |  6 +++---
 src/lib/version/check.sh                  | 12 +++++++-----
 src/lib/version/upgrade.sh                | 12 ++++++++----
 src/pkgctl.in                             |  2 +-
 9 files changed, 84 insertions(+), 38 deletions(-)

(limited to 'doc/man/pkgctl-version-check.1.asciidoc')

diff --git a/contrib/completion/zsh/_devtools.in b/contrib/completion/zsh/_devtools.in
index b427d20..34f90c6 100644
--- a/contrib/completion/zsh/_devtools.in
+++ b/contrib/completion/zsh/_devtools.in
@@ -277,7 +277,7 @@ _pkgctl_cmds=(
 	"release[Release step to commit, tag and upload build artifacts]"
 	"repo[Manage Git packaging repositories and their configuration]"
 	"search[Search for an expression across the GitLab packaging group]"
-	"version[Package version related commands]"
+	"version[Check and manage package versions against upstream]"
 )
 
 _pkgctl_args=(
@@ -287,8 +287,8 @@ _pkgctl_args=(
 
 _pkgctl_version_cmds=(
 	"pkgctl version command"
-	"check[Check if there is an new upstream version available]"
-	"upgrade[Upgrade the PKGBUILD according to the latest available upstream version]"
+	"check[Compares local package versions against upstream versions]"
+	"upgrade[Adjust the PKGBUILD to match the latest upstream version]"
 )
 
 _pkgctl_version_check_args=(
diff --git a/doc/man/pkgctl-version-check.1.asciidoc b/doc/man/pkgctl-version-check.1.asciidoc
index fa5401f..2543bcb 100644
--- a/doc/man/pkgctl-version-check.1.asciidoc
+++ b/doc/man/pkgctl-version-check.1.asciidoc
@@ -3,7 +3,7 @@ pkgctl-version-check(1)
 
 Name
 ----
-pkgctl-version-check - Check if there is an new upstream version available
+pkgctl-version-check - Compares local package versions against upstream
 
 Synopsis
 --------
@@ -12,20 +12,24 @@ pkgctl version check [OPTIONS] [PKGBASE...]
 Description
 -----------
 
-Uses nvchecker, a .nvchecker.toml file and the version specified in the current
-PKGBUILDs pkgver to check if there is a newer package version available to
-which this package could possibly be upgraded.
+Compares the versions of packages in the local packaging repository against
+their latest upstream versions.
 
-The current working directory is used if no PKGBASE is specified.
+Upon execution, it generates a grouped list that provides detailed insights
+into each package's status. For each package, it displays the current local
+version alongside the latest version available upstream.
+
+Outputs a summary of up-to-date packages, out-of-date packages, and any check
+failures.
+
+This simplifies the maintenance of PKGBUILD files, reducing the manual effort
+required to track version changes from upstream sources.
 
 Configuration
 -------------
 
-To provide GitHub or GitLab tokens to nvchecker, a `keyfile.toml` will be
-supplied from `$XDG_CONFIG_HOME`/nvchecker.
-
-See the section on configuration files in linkman:nvchecker[1] for possible options
-which can be utilized in .nvchecker.toml.
+Uses linkman:nvchecker[1] and a `.nvchecker.toml` file located alongside the
+PKGBUILD. Refer to the configuration section in linkman:pkgctl-version[1].
 
 Options
 -------
@@ -36,8 +40,8 @@ Options
 *-h, --help*::
 	Show a help text
 
-Errors
-------
+Exit Codes
+----------
 
 On exit, return one of the following codes:
 
@@ -56,6 +60,7 @@ On exit, return one of the following codes:
 See Also
 --------
 
+linkman:pkgctl-version[1]
 linkman:nvchecker[1]
 
 include::include/footer.asciidoc[]
diff --git a/doc/man/pkgctl-version-upgrade.1.asciidoc b/doc/man/pkgctl-version-upgrade.1.asciidoc
index 7f9cd96..68e6369 100644
--- a/doc/man/pkgctl-version-upgrade.1.asciidoc
+++ b/doc/man/pkgctl-version-upgrade.1.asciidoc
@@ -3,7 +3,7 @@ pkgctl-version-upgrade(1)
 
 Name
 ----
-pkgctl-version-upgrade - Upgrade the PKGBUILD according to the latest available upstream version
+pkgctl-version-upgrade - Adjust the PKGBUILD to match the latest upstream version
 
 Synopsis
 --------
@@ -12,12 +12,25 @@ pkgctl version upgrade [OPTIONS] [PKGBASE...]
 Description
 -----------
 
-Upgrade the PKGBUILD according to the latest available upstream version.
+Streamlines the process of keeping PKGBUILD files up-to-date with the latest
+upstream versions.
 
-Uses nvchecker, a .nvchecker.toml file and the current PKGBUILD pkgver to check
-if there is a newer package version available.
+Upon execution, it automatically adjusts the PKGBUILD file, ensuring that the
+pkgver field is set to match the latest version available from the upstream
+source. In addition to updating the pkgver, this command also resets the pkgrel
+to 1.
 
-The current working directory is used if no PKGBASE is specified.
+Outputs a summary of upgraded packages, up-to-date packages, and any check
+failures.
+
+This simplifies the maintenance of PKGBUILD files, reducing the manual effort
+required to track and implement version changes from upstream sources.
+
+Configuration
+-------------
+
+Uses linkman:nvchecker[1] and a `.nvchecker.toml` file located alongside the
+PKGBUILD. Refer to the configuration section in linkman:pkgctl-version[1].
 
 Options
 -------
@@ -31,6 +44,7 @@ Options
 See Also
 --------
 
+linkman:pkgctl-version[1]
 linkman:nvchecker[1]
 
 include::include/footer.asciidoc[]
diff --git a/doc/man/pkgctl-version.1.asciidoc b/doc/man/pkgctl-version.1.asciidoc
index e71becd..fa83314 100644
--- a/doc/man/pkgctl-version.1.asciidoc
+++ b/doc/man/pkgctl-version.1.asciidoc
@@ -3,7 +3,7 @@ pkgctl-version(1)
 
 Name
 ----
-pkgctl-version - Package version related commands.
+pkgctl-version - Check and manage package versions against upstream
 
 
 Synopsis
@@ -13,7 +13,28 @@ pkgctl version [OPTIONS] [SUBCOMMAND]
 Description
 -----------
 
-Package version related commands such as checking if a package is out of date.
+Commands related to package versions, including checks for outdated packages.
+
+Uses linkman:nvchecker[1] and a `.nvchecker.toml` file located alongside the
+PKGBUILD.
+
+Configuration
+-------------
+
+The `.nvchecker.toml` file must contain a section that matches the
+package's pkgbase. The pkgbase section within the `.nvchecker.toml` file
+specifies the source and method for checking the latest version of the
+corresponding package.
+
+For detailed information on the various configuration options available for the
+`.nvchecker.toml` file, refer to the configuration files section in
+linkman:nvchecker[1]. This documentation provides insights into the possible
+options that can be utilized to customize the version checking process.
+
+To supply GitHub or GitLab tokens to nvchecker, a `keyfile.toml` should be
+placed in the `$XDG_CONFIG_HOME`/nvchecker` directory. This keyfile is
+used for providing the necessary authentication tokens required for
+accessing the GitHub or GitLab API.
 
 Options
 -------
@@ -25,10 +46,10 @@ Subcommands
 -----------
 
 pkgctl version check::
-	Check if there is an new upstream version available
+	Compares local package versions against upstream
 
 pkgctl version upgrade::
-	Upgrade the PKGBUILD according to the latest available upstream version
+	Adjust the PKGBUILD to match the latest upstream version
 
 See Also
 --------
diff --git a/doc/man/pkgctl.1.asciidoc b/doc/man/pkgctl.1.asciidoc
index 929ae9a..d9a1d8c 100644
--- a/doc/man/pkgctl.1.asciidoc
+++ b/doc/man/pkgctl.1.asciidoc
@@ -51,7 +51,7 @@ pkgctl search::
 	Search for an expression across the GitLab packaging group
 
 pkgctl version::
-	Package version related commands
+	Check and manage package versions against upstream
 
 See Also
 --------
diff --git a/src/lib/version.sh b/src/lib/version.sh
index 4340fca..ac810ae 100644
--- a/src/lib/version.sh
+++ b/src/lib/version.sh
@@ -15,11 +15,11 @@ pkgctl_version_usage() {
     cat <<- _EOF_
 		Usage: ${COMMAND} [COMMAND] [OPTIONS]
 
-		Package version related commands.
+		Check and manage package versions against upstream.
 
 		COMMANDS
-		    check      Check if there is a newer version availble
-		    upgrade    Upgrade the PKGBUILD according to the latest available upstream version
+		    check      Compares local package versions against upstream
+		    upgrade    Adjust the PKGBUILD to match the latest upstream version
 
 		OPTIONS
 		    -h, --help    Show this help text
diff --git a/src/lib/version/check.sh b/src/lib/version/check.sh
index cc8827d..006fd80 100644
--- a/src/lib/version/check.sh
+++ b/src/lib/version/check.sh
@@ -28,13 +28,15 @@ pkgctl_version_check_usage() {
 	cat <<- _EOF_
 		Usage: ${COMMAND} [OPTIONS] [PKGBASE]...
 
-		Uses nvchecker, a .nvchecker.toml file and the current PKGBUILD
-		pkgver to check if there is a newer package version available.
+		Compares the versions of packages in the local packaging repository against
+		their latest upstream versions.
 
-		The current working directory is used if no PKGBASE is specified.
+		Upon execution, it generates a grouped list that provides detailed insights
+		into each package's status. For each package, it displays the current local
+		version alongside the latest version available upstream.
 
-		To provide GitHub or GitLab tokens to nvchecker, a keyfile.toml
-		will be supplied from \${XDG_CONFIG_HOME}/nvchecker.
+		Outputs a summary of up-to-date packages, out-of-date packages, and any
+		check failures.
 
 		OPTIONS
 		    -v, --verbose    Display results including up-to-date versions
diff --git a/src/lib/version/upgrade.sh b/src/lib/version/upgrade.sh
index 70513ce..87744b0 100644
--- a/src/lib/version/upgrade.sh
+++ b/src/lib/version/upgrade.sh
@@ -24,12 +24,16 @@ pkgctl_version_upgrade_usage() {
 	cat <<- _EOF_
 		Usage: ${COMMAND} [OPTIONS] [PKGBASE]...
 
-		Upgrade the PKGBUILD according to the latest available upstream version
+		Streamlines the process of keeping PKGBUILD files up-to-date with the latest
+		upstream versions.
 
-		Uses nvchecker, a .nvchecker.toml file and the current PKGBUILD
-		pkgver to check if there is a newer package version available.
+		Upon execution, it automatically adjusts the PKGBUILD file, ensuring that the
+		pkgver field is set to match the latest version available from the upstream
+		source. In addition to updating the pkgver, this command also resets the pkgrel
+		to 1.
 
-		The current working directory is used if no PKGBASE is specified.
+		Outputs a summary of upgraded packages, up-to-date packages, and any check
+		failures.
 
 		OPTIONS
 		    -v, --verbose    Display results including up-to-date versions
diff --git a/src/pkgctl.in b/src/pkgctl.in
index 9deb4b2..50c14b5 100644
--- a/src/pkgctl.in
+++ b/src/pkgctl.in
@@ -27,7 +27,7 @@ usage() {
 		    release Release step to commit, tag and upload build artifacts
 		    repo    Manage Git packaging repositories and their configuration
 		    search  Search for an expression across the GitLab packaging group
-		    version Package version related commands
+		    version Check and manage package versions against upstream
 
 		OPTIONS
 		    -h, --help     Show this help text
-- 
cgit v1.2.3-54-g00ecf