From cd0bd7269f35ccb559f81abfda62c69ae06bce79 Mon Sep 17 00:00:00 2001 From: Adam Perkowski Date: Tue, 26 Nov 2024 19:26:22 +0100 Subject: [PATCH] docs(README): add installation & usage instructions Signed-off-by: Adam Perkowski --- .gitignore | 1 + README.md | 136 ++++++++++++++++++++++++++++++++++++++++++++++++++--- linux | 51 ++++++++++++++++++++ nvrs.tape | 61 ++++++++++++++++++++++++ 4 files changed, 242 insertions(+), 7 deletions(-) create mode 100644 linux create mode 100644 nvrs.tape diff --git a/.gitignore b/.gitignore index d40e8fa..ebc21c9 100644 --- a/.gitignore +++ b/.gitignore @@ -4,3 +4,4 @@ oldver.json keyfile.toml *_old *.old +*.gif diff --git a/README.md b/README.md index a4fcb09..4294cd3 100644 --- a/README.md +++ b/README.md @@ -1,11 +1,10 @@
# nvrs -🚦 fast new version checker for software releases πŸ¦€
-[nvchecker](https://github.com/lilydjwg/nvchecker) rewritten in Rust +🚦 fast new version checker for software releases πŸ¦€ -![Build Status](https://img.shields.io/github/actions/workflow/status/adamperkowski/nvrs/rust.yml?style=for-the-badge&labelColor=%23a8127d&color=%23336795) ![docs.rs](https://img.shields.io/docsrs/nvrs?style=for-the-badge&labelColor=%23a8127d&color=%23336795)
-![GitHub Contributors](https://img.shields.io/github/contributors-anon/adamperkowski/nvrs?style=for-the-badge&labelColor=%23a8127d&color=%23336795) ![GitHub Repo Size](https://img.shields.io/github/repo-size/adamperkowski/nvrs?style=for-the-badge&labelColor=%23a8127d&color=%23336795) ![Repo Created At](https://img.shields.io/github/created-at/adamperkowski/nvrs?style=for-the-badge&labelColor=%23a8127d&color=%23336795) +![Build Status](https://img.shields.io/github/actions/workflow/status/adamperkowski/nvrs/rust.yml?style=for-the-badge&labelColor=%23a8127d&color=%23336795) [![docs.rs](https://img.shields.io/docsrs/nvrs?style=for-the-badge&labelColor=%23a8127d&color=%23336795)](#documentation)
+[![GitHub Contributors](https://img.shields.io/github/contributors-anon/adamperkowski/nvrs?style=for-the-badge&labelColor=%23a8127d&color=%23336795)](https://github.com/adamperkowski/nvrs/graphs/contributors) ![GitHub Repo Size](https://img.shields.io/github/repo-size/adamperkowski/nvrs?style=for-the-badge&labelColor=%23a8127d&color=%23336795) ![Repo Created At](https://img.shields.io/github/created-at/adamperkowski/nvrs?style=for-the-badge&labelColor=%23a8127d&color=%23336795) ![banner](/banner.webp) @@ -18,8 +17,11 @@ new features & bugfixes are being pushed every day you may encounter some issues. please consider [submitting feedback](https://github.com/adamperkowski/nvrs/issues/new/choose) if you do. ## Features +### [nvchecker](https://github.com/lilydjwg/nvchecker) compatibility +check the [release notes](https://github.com/adamperkowski/nvrs/releases) for compatibility updates + ### Speed -ka-chow +ka-chow | command | time per **updated** package | details | |---------------|------------------------------|--------------------------------------------------------| @@ -28,12 +30,132 @@ you may encounter some issues. please consider [submitting feedback](https://git | `nvrs --take` | ~ 0.001s | depends on disk speed | ### Sources -**WIP** - - `aur` - `github` - `gitlab` (with custom hosts) +## Installation +Packaging status + +
+Arch Linux + +[nvrs](https://aur.archlinux.org/packages/nvrs) is available as a package in the [AUR](https://aur.archlinux.org).
+you can install it with your preferred [AUR helper](https://wiki.archlinux.org/title/AUR_helpers), example: + +```sh +paru -S nvrs +``` + +or manually: + +```sh +git clone https://aur.archlinux.org/nvrs.git +cd nvrs +makepkg -si +``` + +
+ +
+Cargo + +[nvrs](https://crates.io/crates/nvrs) can be installed via [Cargo](https://doc.rust-lang.org/cargo) with: + +```sh +cargo install nvrs +``` + +note that crates installed using `cargo install` require manual updating with `cargo install --force`. + +
+ +
+Manual + +1. Download the latest binary from [GitHub's release page](https://github.com/adamperkowski/nvrs/releases/latest) +2. Allow execution +```sh +chmod +x nvrs +``` +3. Move the file to a directory in `$PATH` (using `/usr/bin` as an example) +```sh +sudo mv nvrs /usr/bin/nvrs +``` + +
+ +## Usage +nvrs relies on a configuration file. see [configuration](#configuration). + +Packaging status + +the core commands are: +- `nvrs` - fetches latest versions of defined packages +- `nvrs --cmp` - compares newver with oldver and displays differences +- `nvrs --take` - automatically updates oldver. takes in a comma-separated list of package names (`ALL` for all packages) +- `nvrs --nuke` - deletes packages from all files. takes in a comma-separated list of names (yes, just like a hitman) +- the `--no-fail` flag - as the name suggests, specifying this will make nvrs not exit on recoverable errors + +### Example usage +```sh +# download the example configuration file +curl -L 'https://github.com/adamperkowski/nvrs/raw/main/nvrs.toml' -o nvrs.toml + +# fetch latest package versions (should return `NONE -> version` for all packages) +nvrs --no-fail + +# compare them to latest known versions (should also return `NONE -> version`) +nvrs -c + +# update the known versions +nvrs -t ALL +``` + +## Configuration +nvrs relies on a configuration file ([example](/nvrs.toml)) containing basic settings, such as `oldver`, `newver` & `keyfile` paths, as well as [package entries](#package-entries). supported config paths: +- `$XDG_CONFIG_HOME/nvrs.toml` (`~/.config/nvrs.toml` if the variable is not set) +- `./nvrs.toml` +- custom paths set with `nvrs --config` + +### `__config__` table +this configures the behavior of nvrs. see the [example config](/nvrs.toml#L7-L10). + +available fields: + +| name | description | type | required | +|-----------|-----------------------------------------------------------------|--------|----------| +| `oldver` | path to the `oldver` file | string | βœ”οΈ | +| `newver` | path to the `newver` file | string | βœ”οΈ | +| `keyfile` | path to a keyfile (see [keyfile structure](#keyfile-structure)) | string | ❌ | + +### Package entries + +[example](/nvrs.toml#L12-L15) + +package entries are custom entries in the main config file. they contain values such as: + +| name | description | type | required | custom | +|-------------|---------------------------------------------------------------------------|--------|----------|--------| +| `source` | see [sources](#sources) | string | βœ”οΈ | ❌ | +| source name | the "target". eg. repo path for `github` | string | βœ”οΈ | βœ”οΈ | +| `host` | domain name the source is hosted on | string | ❌ | ❌ | +| `prefix` | the prefix used in releases / tags
example: `v` for tags like `v0.1.0` | string | ❌ | ❌ | + +### Keyfile structure +this file contains API keys for various [sources](#sources). example can be found [here](/n_keyfile.toml). + +```toml +[keys] +github = "your_secret_github_api_key_that_you_shouldnt_push_to_a_public_nor_a_private_remote_repo_because_there_will_definitely_be_serious_consequences_sooner_or_later_if_you_do_trust_me_just_dont" +gitlab = "remember_to_replace_the_example_values_here_here_with_your_actual_keys_otherwise_it_wont_work_but_dont_push_keyfiles_to_remote_repos" +``` + +"I think that example value is not long enough" - orhun + +## Documentation +the nvrs library documentation can be found at [docs.rs/nvrs](https://docs.rs/nvrs/latest/nvrs) + ## Credits - [依云](https://github.com/lilydjwg) | the original [nvchecker](https://github.com/lilydjwg/nvchecker) - [orhun](https://github.com/orhun) | the idea diff --git a/linux b/linux new file mode 100644 index 0000000..3c412fb --- /dev/null +++ b/linux @@ -0,0 +1,51 @@ +#!/bin/sh -e + +# Prevent execution if this script was only partially downloaded +{ +rc='\033[0m' +red='\033[0;31m' + +check() { + exit_code=$1 + message=$2 + + if [ "$exit_code" -ne 0 ]; then + printf '%sERROR: %s%s\n' "$red" "$message" "$rc" + exit 1 + fi + + unset exit_code + unset message +} + +findArch() { + case "$(uname -m)" in + x86_64|amd64) arch="x86_64" ;; + aarch64|arm64) arch="aarch64" ;; + *) check 1 "Unsupported architecture" + esac +} + +getUrl() { + case "${arch}" in + x86_64) echo "https://github.com/ChrisTitusTech/linutil/releases/latest/download/linutil";; + *) echo "https://github.com/ChrisTitusTech/linutil/releases/latest/download/linutil-${arch}";; + esac +} + +findArch +temp_file=$(mktemp) +check $? "Creating the temporary file" + +curl -fsL "$(getUrl)" -o "$temp_file" +check $? "Downloading linutil" + +chmod +x "$temp_file" +check $? "Making linutil executable" + +"$temp_file" +check $? "Executing linutil" + +rm -f "$temp_file" +check $? "Deleting the temporary file" +} # End of wrapping diff --git a/nvrs.tape b/nvrs.tape new file mode 100644 index 0000000..0159781 --- /dev/null +++ b/nvrs.tape @@ -0,0 +1,61 @@ +# VHS +# https://github.com/charmbracelet/vhs + +Output nvrs.gif + +Require echo + +Set Shell "zsh" +Set FontSize 32 +Set Width 1280 +Set Height 720 +Set TypingSpeed 0ms +Set Theme { "black": "#000D19", "red": "#7D0C0C", "green": "#0C7D45", "yellow": "#7D750C", "blue": "#0C567E", "magenta": "#6E1D57", "cyan": "#12748F", "white": "#A3A3A3", "brightBlack": "#000D19", "brightRed": "#951313", "brightGreen": "#16A85F", "brightYellow": "#ABA119", "brightBlue": "#1A76A8", "brightMagenta": "#A01576", "brightCyan": "#188AA9", "brightWhite": "#A3A3A3", "background": "#00050D", "foreground": "#A3A3A3", "selection": "#6E1D57", "cursor": "#A3A3A3" } + +Hide +Type "source /usr/share/zsh/plugins/zsh-autosuggestions/zsh-autosuggestions.plugin.zsh" +Enter +Type "source /usr/share/zsh/plugins/zsh-syntax-highlighting/zsh-syntax-highlighting.plugin.zsh" +Enter +Ctrl+L +Sleep 100ms +Show + +Set TypingSpeed 30ms + +Type "1. fetch latest versions of defined packages" +Sleep 1s +Ctrl+U +Sleep 500ms +Type "nvrs" +Sleep 500ms +Enter + +Sleep 1.5s +Ctrl+L + +Type "2. compare them to latest known versions" +Sleep 1s +Ctrl+U +Sleep 500ms +Type "nvrs --cmp" +Sleep 500ms +Enter + +Sleep 1.5s +Ctrl+L + +Type "3. update the known versions" +Sleep 1s +Ctrl+U +Sleep 500ms +Type "nvrs --take ALL" +Sleep 500ms +Enter + +Sleep 2s + +Enter +Type "4. go on github.com/adamperkowski/nvrs & leave a star" + +Sleep 4s