From 6054c869e1b9b853aa7408261e477dcb187ff498 Mon Sep 17 00:00:00 2001 From: Christian Heusel 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 Signed-off-by: Christian Heusel --- 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 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 --- 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 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 --- 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