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>
---
 src/lib/version.sh | 56 ++++++++++++++++++++++++++++++++++++++++++++++++++++++
 1 file changed, 56 insertions(+)
 create mode 100644 src/lib/version.sh

(limited to 'src/lib/version.sh')

diff --git a/src/lib/version.sh b/src/lib/version.sh
new file mode 100644
index 0000000..826b306
--- /dev/null
+++ b/src/lib/version.sh
@@ -0,0 +1,56 @@
+#!/hint/bash
+#
+# SPDX-License-Identifier: GPL-3.0-or-later
+
+[[ -z ${DEVTOOLS_INCLUDE_VERSION_SH:-} ]] || return 0
+DEVTOOLS_INCLUDE_VERSION_SH=1
+
+_DEVTOOLS_LIBRARY_DIR=${_DEVTOOLS_LIBRARY_DIR:-@pkgdatadir@}
+
+set -e
+
+
+pkgctl_version_usage() {
+	local -r COMMAND=${_DEVTOOLS_COMMAND:-${BASH_SOURCE[0]##*/}}
+    cat <<- _EOF_
+		Usage: ${COMMAND} [COMMAND] [OPTIONS]
+
+		Package version related commands.
+
+		COMMANDS
+		    check    Check if there is a newer version availble
+
+		OPTIONS
+		    -h, --help    Show this help text
+
+		EXAMPLES
+		    $ ${COMMAND} check libfoo linux libbar
+_EOF_
+}
+
+pkgctl_version() {
+	if (( $# < 1 )); then
+		pkgctl_version_usage
+		exit 0
+	fi
+
+	while (( $# )); do
+		case $1 in
+			-h|--help)
+				pkgctl_version_usage
+				exit 0
+				;;
+			check)
+				_DEVTOOLS_COMMAND+=" $1"
+				shift
+				# shellcheck source=src/lib/version/check.sh
+				source "${_DEVTOOLS_LIBRARY_DIR}"/lib/version/check.sh
+				pkgctl_version_check "$@"
+				exit 0
+				;;
+			*)
+				die "invalid argument: %s" "$1"
+				;;
+		esac
+	done
+}
-- 
cgit v1.2.3-54-g00ecf


From 6054c869e1b9b853aa7408261e477dcb187ff498 Mon Sep 17 00:00:00 2001
From: Christian Heusel <christian@heusel.eu>
Date: Fri, 5 Jan 2024 19:10:38 +0100
Subject: feat(upgrade): introduce the version upgrade subcommand

This subcommand applies the detected upstream version upgrades to a
PKGBUILD.

Component: pkgctl version upgrade
Co-authored-by: Levente Polyak <anthraxx@archlinux.org>
Signed-off-by: Christian Heusel <christian@heusel.eu>
---
 contrib/completion/bash/devtools.in       |   7 ++
 contrib/completion/zsh/_devtools.in       |   6 ++
 doc/man/pkgctl-version-upgrade.1.asciidoc |  33 +++++++++
 doc/man/pkgctl-version.1.asciidoc         |   4 ++
 src/lib/version.sh                        |  11 ++-
 src/lib/version/upgrade.sh                | 108 ++++++++++++++++++++++++++++++
 6 files changed, 168 insertions(+), 1 deletion(-)
 create mode 100644 doc/man/pkgctl-version-upgrade.1.asciidoc
 create mode 100644 src/lib/version/upgrade.sh

(limited to 'src/lib/version.sh')

diff --git a/contrib/completion/bash/devtools.in b/contrib/completion/bash/devtools.in
index f1084ab..101bd78 100644
--- a/contrib/completion/bash/devtools.in
+++ b/contrib/completion/bash/devtools.in
@@ -339,6 +339,7 @@ _pkgctl_repo_switch_opts() {
 
 _pkgctl_version_cmds=(
 	check
+	upgrade
 )
 
 _pkgctl_version_check_args=(
@@ -347,6 +348,12 @@ _pkgctl_version_check_args=(
 
 _pkgctl_version_check_opts() { _filedir -d; }
 
+_pkgctl_version_upgrade_args=(
+	-h --help
+)
+
+_pkgctl_version_upgrade_opts() { _filedir -d; }
+
 _pkgctl_repo_web_args=(
 	--print
 	-h --help
diff --git a/contrib/completion/zsh/_devtools.in b/contrib/completion/zsh/_devtools.in
index 575c327..38bf582 100644
--- a/contrib/completion/zsh/_devtools.in
+++ b/contrib/completion/zsh/_devtools.in
@@ -288,6 +288,7 @@ _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]"
 )
 
 _pkgctl_version_check_args=(
@@ -295,6 +296,11 @@ _pkgctl_version_check_args=(
 	'*:git_dir:_files -/'
 )
 
+_pkgctl_version_upgrade_args=(
+	'(-h --help)'{-h,--help}'[Display usage]'
+	'*:git_dir:_files -/'
+)
+
 _pkgctl_diff_args=("${_diffpkg_args[@]}")
 
 _handle_subcommands() {
diff --git a/doc/man/pkgctl-version-upgrade.1.asciidoc b/doc/man/pkgctl-version-upgrade.1.asciidoc
new file mode 100644
index 0000000..3d5d882
--- /dev/null
+++ b/doc/man/pkgctl-version-upgrade.1.asciidoc
@@ -0,0 +1,33 @@
+pkgctl-version-upgrade(1)
+=========================
+
+Name
+----
+pkgctl-version-upgrade - Upgrade the PKGBUILD according to the latest available upstream version
+
+Synopsis
+--------
+pkgctl version upgrade [OPTIONS] [PKGBASE...]
+
+Description
+-----------
+
+Upgrade the PKGBUILD according to the latest available upstream version.
+
+Uses nvchecker, a .nvchecker.toml file and the current PKGBUILD pkgver to check
+if there is a newer package version available.
+
+The current working directory is used if no PKGBASE is specified.
+
+Options
+-------
+
+*-h, --help*::
+	Show a help text
+
+See Also
+--------
+
+linkman:nvchecker[1]
+
+include::include/footer.asciidoc[]
diff --git a/doc/man/pkgctl-version.1.asciidoc b/doc/man/pkgctl-version.1.asciidoc
index 53a72f3..e71becd 100644
--- a/doc/man/pkgctl-version.1.asciidoc
+++ b/doc/man/pkgctl-version.1.asciidoc
@@ -27,9 +27,13 @@ Subcommands
 pkgctl version check::
 	Check if there is an new upstream version available
 
+pkgctl version upgrade::
+	Upgrade the PKGBUILD according to the latest available upstream version
+
 See Also
 --------
 
 linkman:pkgctl-version-check[1]
+linkman:pkgctl-version-upgrade[1]
 
 include::include/footer.asciidoc[]
diff --git a/src/lib/version.sh b/src/lib/version.sh
index 826b306..14cd810 100644
--- a/src/lib/version.sh
+++ b/src/lib/version.sh
@@ -18,7 +18,8 @@ pkgctl_version_usage() {
 		Package version related commands.
 
 		COMMANDS
-		    check    Check if there is a newer version availble
+		    check      Check if there is a newer version availble
+		    upgrade    Upgrade the PKGBUILD according to the latest available upstream version
 
 		OPTIONS
 		    -h, --help    Show this help text
@@ -48,6 +49,14 @@ pkgctl_version() {
 				pkgctl_version_check "$@"
 				exit 0
 				;;
+			upgrade)
+				_DEVTOOLS_COMMAND+=" $1"
+				shift
+				# shellcheck source=src/lib/version/upgrade.sh
+				source "${_DEVTOOLS_LIBRARY_DIR}"/lib/version/upgrade.sh
+				pkgctl_version_upgrade "$@"
+				exit 0
+				;;
 			*)
 				die "invalid argument: %s" "$1"
 				;;
diff --git a/src/lib/version/upgrade.sh b/src/lib/version/upgrade.sh
new file mode 100644
index 0000000..704431a
--- /dev/null
+++ b/src/lib/version/upgrade.sh
@@ -0,0 +1,108 @@
+#!/bin/bash
+#
+# SPDX-License-Identifier: GPL-3.0-or-later
+#
+[[ -z ${DEVTOOLS_INCLUDE_VERSION_UPGRADE_SH:-} ]] || return 0
+DEVTOOLS_INCLUDE_VERSION_UPGRADE_SH=1
+
+_DEVTOOLS_LIBRARY_DIR=${_DEVTOOLS_LIBRARY_DIR:-@pkgdatadir@}
+# shellcheck source=src/lib/common.sh
+source "${_DEVTOOLS_LIBRARY_DIR}"/lib/common.sh
+# shellcheck source=src/lib/version/check.sh
+source "${_DEVTOOLS_LIBRARY_DIR}"/lib/version/check.sh
+# shellcheck source=src/lib/util/pkgbuild.sh
+source "${_DEVTOOLS_LIBRARY_DIR}"/lib/util/pkgbuild.sh
+
+source /usr/share/makepkg/util/message.sh
+
+set -e
+
+pkgctl_version_upgrade_usage() {
+	local -r COMMAND=${_DEVTOOLS_COMMAND:-${BASH_SOURCE[0]##*/}}
+	cat <<- _EOF_
+		Usage: ${COMMAND} [OPTIONS] [PKGBASE]...
+
+		Upgrade the PKGBUILD according to the latest available upstream version
+
+		Uses nvchecker, a .nvchecker.toml file and the current PKGBUILD
+		pkgver to check if there is a newer package version available.
+
+		The current working directory is used if no PKGBASE is specified.
+
+		OPTIONS
+		    -h, --help          Show this help text
+
+		EXAMPLES
+		    $ ${COMMAND} neovim vim
+_EOF_
+}
+
+pkgctl_version_upgrade() {
+	local path upstream_version result
+	local pkgbases=()
+
+	while (( $# )); do
+		case $1 in
+			-h|--help)
+				pkgctl_version_upgrade_usage
+				exit 0
+				;;
+			--)
+				shift
+				break
+				;;
+			-*)
+				die "invalid argument: %s" "$1"
+				;;
+			*)
+				pkgbases=("$@")
+				break
+				;;
+		esac
+	done
+
+	if ! command -v nvchecker &>/dev/null; then
+		die "The \"$_DEVTOOLS_COMMAND\" command requires 'nvchecker'"
+	fi
+
+	# Check if used without pkgbases in a packaging directory
+	if (( ${#pkgbases[@]} == 0 )); then
+		if [[ -f PKGBUILD ]]; then
+			pkgbases=(".")
+		else
+			pkgctl_version_upgrade_usage
+			exit 1
+		fi
+	fi
+
+	for path in "${pkgbases[@]}"; do
+		pushd "${path}" >/dev/null
+
+		if [[ ! -f "PKGBUILD" ]]; then
+			die "No PKGBUILD found for ${path}"
+		fi
+
+		# reset common PKGBUILD variables
+		unset pkgbase pkgname arch source pkgver pkgrel validpgpkeys
+		# shellcheck source=contrib/makepkg/PKGBUILD.proto
+		. ./PKGBUILD
+		pkgbase=${pkgbase:-$pkgname}
+
+		if ! upstream_version=$(get_upstream_version); then
+			die "Failed to get latest upstream version for %s" "${pkgbase}"
+		fi
+
+		if ! result=$(vercmp "${upstream_version}" "${pkgver}"); then
+			die "Failed to compare version %s against %s" "${upstream_version}" "${pkgver}"
+		fi
+
+		if (( result > 0 )); then
+			msg_success "${BOLD}${pkgbase}${ALL_OFF}: upgrading from version ${PURPLE}${pkgver}${ALL_OFF} to ${DARK_GREEN}${upstream_version}${ALL_OFF}"
+
+			pkgbuild_set_pkgver "${upstream_version}"
+			pkgbuild_set_pkgrel 1
+		fi
+
+		popd >/dev/null
+	done
+}
-- 
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 'src/lib/version.sh')

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 'src/lib/version.sh')

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