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>
---
 doc/man/pkgctl-version-upgrade.1.asciidoc | 33 +++++++++++++++++++++++++++++++
 1 file changed, 33 insertions(+)
 create mode 100644 doc/man/pkgctl-version-upgrade.1.asciidoc

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

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[]
-- 
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-upgrade.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 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-upgrade.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

