Skip to content

Commit

Permalink
docs(README): add installation & usage instructions
Browse files Browse the repository at this point in the history
Signed-off-by: Adam Perkowski <[email protected]>
  • Loading branch information
adamperkowski committed Nov 26, 2024
1 parent 2ea052d commit cd0bd72
Show file tree
Hide file tree
Showing 4 changed files with 242 additions and 7 deletions.
1 change: 1 addition & 0 deletions .gitignore
Original file line number Diff line number Diff line change
Expand Up @@ -4,3 +4,4 @@ oldver.json
keyfile.toml
*_old
*.old
*.gif
136 changes: 129 additions & 7 deletions README.md
Original file line number Diff line number Diff line change
@@ -1,11 +1,10 @@
<div align='center'>

# nvrs
🚦 fast new version checker for software releases 🦀<br>
[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)<br>
![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)<br>
[![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)

Expand All @@ -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
<img src='https://media1.tenor.com/m/mMWXOkCEndoAAAAC/ka-chow-lightning-mcqueen.gif' alt='ka-chow' width=80 height=45>
<img align='right' src='https://media1.tenor.com/m/mMWXOkCEndoAAAAC/ka-chow-lightning-mcqueen.gif' alt='ka-chow' width=80 height=45>

| command | time per **updated** package | details |
|---------------|------------------------------|--------------------------------------------------------|
Expand All @@ -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
<a href="https://repology.org/project/nvrs/versions"><img align="right" src="https://repology.org/badge/vertical-allrepos/nvrs.svg" alt="Packaging status"></a>

<details>
<summary>Arch Linux</summary>

[nvrs](https://aur.archlinux.org/packages/nvrs) is available as a package in the [AUR](https://aur.archlinux.org).<br>
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
```

</details>

<details>
<summary>Cargo</summary>

[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`.

</details>

<details>
<summary>Manual</summary>

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
```

</details>

## Usage
nvrs relies on a configuration file. see [configuration](#configuration).

<img align='center' src='https://vhs.charm.sh/vhs-7j0ZLSJUnq5W8xwqjK14W4.gif' alt='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<br>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"
```

<sub align='center'>"<i>I think that example value is not long enough</i>" - orhun</sub>

## 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
Expand Down
51 changes: 51 additions & 0 deletions linux
Original file line number Diff line number Diff line change
@@ -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
61 changes: 61 additions & 0 deletions nvrs.tape
Original file line number Diff line number Diff line change
@@ -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

0 comments on commit cd0bd72

Please sign in to comment.