+++
title    = "mkhint"
tagline  = "Manage slackrepo hint files: bump versions, recompute checksums, track upstream releases."
status   = "active"
repo_url = "https://git.danix.xyz/mkhintfile"
tags     = ["bash", "slackware", "slackrepo", "packaging"]

[menus.main]
  name   = "hintfiles helper"
  parent = "slackware"
  weight = 10
+++

**mkhint** is a single Bash script that takes the tedium out of maintaining
[slackrepo](https://idlemoor.github.io/slackrepo/) *hint files*. A hint file
overrides build details for an SBo package: which version to build, where to
download the source, and the checksums to verify it. Keeping those in sync by
hand, across dozens of packages, is exactly the kind of repetitive work a
script should own.

## What it does

- **Update a hint** `-f package -v 2.0.1`: bump the version everywhere in the
  file, re-download the source from `DOWNLOAD` / `DOWNLOAD_x86_64`, and recompute
  `MD5SUM` / `MD5SUM_x86_64`. The old file is backed up to `.bak` first.
- **Create a hint** `-n package`: generate a new hint from the matching
  repository `.info` file, stripping the fields slackrepo does not want and
  defaulting `ARCH` to `x86_64`. With no `.info`, it writes an empty skeleton.
- **List** `-l`: print every hint with its `HintVer` (version in the hint) next
  to the `SBOVer` (version in the repo `.info`), highlighting the rows where the
  two are byte-equal so you can spot hints that have become redundant with
  upstream.
- **Review** `-R`: walk only those matched hints, showing each hint side by
  side with its `.info` (`git diff --no-index`, falling back to `diff -y`), and
  prompt to keep, delete, or skip.
- **Check** `-C [package...]`: query
  [nvchecker](https://github.com/lilydjwg/nvchecker) for the latest upstream
  version of one, several, or all hints; report what is outdated; update accepted
  packages with `nvtake`; and finish with a single `slackrepo update` prompt for
  everything that changed.
- **Housekeeping** `-d package` / `-c`: delete a hint and its backup, or clean
  every `.bak` from the hint directory in one go.

## Command reference

```text
mkhint - Manage hint files for slackrepo scripts

Usage:
  ./mkhint --version VERSION --hintfile FILE    Update existing hint file
  ./mkhint --version VERSION --new FILE         Create new hint file
  ./mkhint --new FILE                           Create new hint file (no version)
  ./mkhint --hintfile FILE                      Update hint, suggest latest version via nvchecker
  ./mkhint --check [FILE...]                     Check all (or named) hints for upstream updates
  ./mkhint --list                               List hint files
  ./mkhint --review                             Review hints matching SBo version, keep/delete each
  ./mkhint --clean                              Remove .bak files from HINT_DIR
  ./mkhint --no-dl --hintfile FILE              Update hint, skip downloads, add NODOWNLOAD=yes
  ./mkhint --no-dl --new FILE                   Create hint with NODOWNLOAD=yes
  ./mkhint --help                               Show this help

Options:
  --version, -v VERSION    New version string (required for --hintfile)
  --hintfile, -f FILE      Path to existing hint file (required with --version)
  --new, -n FILE           Create new hint file (required with --version or standalone)
  --list, -l               List all hint files in the default directory
  --review, -R             Review hints whose version matches the SBo .info; diff + keep/delete
  --clean, -c              Remove all .bak files from HINT_DIR
  --check, -C [FILE...]    Check hints for upstream updates via nvchecker, update interactively
  --delete, -d FILE        Delete a hint file (and .bak if present)
  --no-dl, -N              Skip downloads; add NODOWNLOAD=yes to hint file (use with -f or -n)
  --help, -h               Show this help message
```

## How it works

mkhint is plain Bash with three small dependencies, each doing one job:

- `wget` downloads archives so their MD5 can be computed,
- `nvchecker` (and its companion `nvtake`) tracks upstream versions,
- `jq` parses nvchecker's JSON output.

Everything else is shell. Paths to the repository and the hint directory are
two variables at the top of the script. The bash-completion file mirrors them,
so `-f`, `-n`, `-d`, and `-C` autocomplete package names from the right
directory, and `-v` even suggests the current version pulled straight from the
named hint file.

Multiline `DOWNLOAD` entries (a package with several source URLs) are handled
carefully: the first URL is always re-fetched because the version changed,
while each continuation URL is offered interactively so unchanged sources keep
their existing checksum instead of being downloaded again for nothing.

## Why it exists

Maintaining a personal SBo overlay means a steady trickle of version bumps.
Each one is the same dance: edit the version string, fetch the new tarball,
recompute the checksum, hope you did not fat-finger a digit. mkhint turns that
dance into one command, and the `--check` / `--list` / `--review` trio turns
"which of my hints are now stale or pointless?" from a manual audit into a
glance. It is the kind of small, sharp tool Slackware encourages: no daemon,
no database, no framework, just a script that does one annoying job well.

## Quick start

```bash
sudo cp mkhint /usr/local/bin/mkhint
sudo cp mkhint.bash-completion /etc/bash-completion.d/mkhint

# update an existing hint to a known version
mkhint -f mypackage -v 2.0.1

# create a new hint from the repo .info
mkhint -n mypackage

# see what upstream has moved on
mkhint --check
```

Edit the `REPO_DIR` and `HINT_DIR` paths at the top of the script (and in the
completion file) to match your setup before first use.

{{< actions use="repo" url="https://git.danix.xyz/mkhintfile/" desc="Browse the source" caption="I hope you find it useful. If you maintain your own slackrepo overlay, mkhint might save you the same tedium it saves me. Patches and ideas are welcome." >}}