Finding packages
search and info, deprecated and yanked versions
Before you depend on something you want to know it exists, what it is called
exactly, which versions there are, who published it and whether its publisher
still recommends it. Two commands answer all of that: search to find, and
info to read. Neither changes anything, and neither needs a project.
What you will be able to do
- search a hub by words, kind of package, platform or owner;
- read everything a hub knows about one package;
- tell an ordinary version from a deprecated or yanked one;
- page through long results and get them as JSON.
Search
gritpack search takes words and finds them in package names, scopes,
descriptions and keywords:
$ gritpack search greet
@ada/greet 0.2.0 ecosystem=native score=900 dialect=c/c23 variants=2 — A tiny C library that says hello
...
@ada/hello-tool 1.1.0 ecosystem=native score=60 dialect=application/cli variants=2 — Prints a friendly greeting
...
Each line is one package, with its newest version first. The fields:
| Field | Meaning |
|---|---|
ecosystem | native for Gritpack packages, cargo for crates in the hub's Cargo registry |
score | how well it matched; an exact name match scores highest |
dialect | what kind of package it is |
variants | how many variants were published, across versions and platforms |
| after the dash | the package's description |
The ranking is the same every time for the same hub and the same words; it does not depend on downloads or popularity, which Gritpack does not track.
With no words, search lists packages in name order. When nothing matches,
search prints nothing and still succeeds; with --json you get an empty
results list.
Narrowing a search
| Option | Keeps only |
|---|---|
--ecosystem native or cargo | one ecosystem |
--dialect c/c23 | that kind of package |
--encoding source/utf8 | that encoding |
--target x86_64-unknown-linux-gnu | builds for that platform |
--version '^1.2' | packages with a version in that range |
--owner <account-id> | packages published by that account |
--limit 10 | at most that many results (default 25) |
This finds the command-line applications on the public hub that were built for Apple silicon Macs, and counts only those variants:
$ gritpack search --dialect application/cli --target aarch64-apple-darwin --from get.gritpack.org
@frogfish/gritpack 1.2.10 ecosystem=native score=0 dialect=application/cli variants=1 — Universal package, module-graph, and software distribution client [deprecated: Package renamed to gritpack. Install with: gritpack install gritpack --from get.gritpack.org]
gritpack 1.2.63 ecosystem=native score=0 dialect=application/cli variants=25 — Universal package, module-graph, and software distribution client
gritpack-installer 1.2.63 ecosystem=native score=0 dialect=application/cli variants=23 — Installs one application, and Gritpack when it is missing
(--from get.gritpack.org asks the public hub even when your default login
points at a private one; see the end of this chapter.)
More than one page
When there are more results than --limit, the last line is a cursor:
$ gritpack search --dialect c/c23 --limit 2
@ada/greet 0.2.0 ecosystem=native score=0 dialect=c/c23 variants=2 — A tiny C library that says hello
@ada/textkit 1.0.1 ecosystem=native score=0 dialect=c/c23 variants=1 — Small text helpers for C programs
next_cursor=7b22736368656d61...
Pass it back with the same words and options to get the next page:
gritpack search --dialect c/c23 --limit 2 --cursor 7b22736368656d61...
If the hub's catalogue changed in between, the cursor is refused; start again from the first page.
On a terminal, long results go through a pager (less by default). Chapter 29
says how to choose another or turn it off.
Info
gritpack info shows one package by its exact name:
$ gritpack info @ada/greet
@ada/greet 0.2.0 (native)
A tiny C library that says hello
dialect: c/c23
versions: 0.2.0, 0.1.0
variants: 2
license: MIT
owner: 01a1e860-95df-7c60-bbe1-5db0fd349f05
...
sha256: b2d9d2e08f0bdfc4e7f87385e0e37647b04b4a4ac3a046fdb98f1197f00cc902
The first block is the newest version: its description, variant, every version you can choose, its licence, the account that owns the name, and the digest of its package file. To read an older version, name it:
$ gritpack info @ada/greet --version 0.1.0
@ada/greet 0.1.0 (native)
A tiny C library that says hello
deprecated: Use 0.2 or later
dialect: c/c23
versions: 0.1.0
...
--version takes a range too, such as --version '^0.1'.
A native package and a Cargo crate may share a name on one hub. info shows
each of them, one block per ecosystem; --ecosystem native or
--ecosystem cargo picks one.
The whole record as JSON
info --json gives everything the hub knows, including each version's README,
keywords, licence files, dependencies and publication time:
$ gritpack info gritpack --json
{
"families": [
{
"ecosystem": "native",
"family": {
"name": "gritpack",
"publications": [
{
...
"dependencies": [],
"description": "Universal package, module-graph, and software distribution client",
"dialect": "application/cli",
...
"license": "LicenseRef-Frogfish-Binary-License-1.0",
...
"readme": {
"markdown": "# Gritpack\n\nGritpack is a package manager for projects that use more than one language.\n...
Pick fields out with --jq. This prints each version and its lifecycle:
$ gritpack info @ada/greet --jq '.families[0].family.publications[] | .version + " " + (.lifecycle|tostring)'
0.2.0 {}
0.1.0 {"deprecation":{"deprecated_at":1794900112,"message":"Use 0.2 or later"}}
Chapter 27 covers --json, --json=fields and --jq for every command.
Deprecated and yanked versions
A published version never changes, but its publisher can still tell you something about it.
Deprecated means "this still works, but please move on". The version stays
available. info shows the message on that version, and search shows it when
the newest version is deprecated, as for the public hub's renamed package:
$ gritpack search gritpack
...
@frogfish/gritpack 1.2.10 ecosystem=native score=900 dialect=application/cli variants=3 — Universal package, module-graph, and software distribution client [deprecated: Package renamed to gritpack. Install with: gritpack install gritpack --from get.gritpack.org]
...
Gritpack does not stop you from choosing a deprecated version; read the message and decide.
Yanked means "do not start using this". A yanked version disappears from
info and from new resolutions:
$ gritpack info @ada/greet --version 0.1.1
package @ada/greet was not found
A project whose lock already names a yanked version keeps working: sync
still installs it, so a yank never breaks a build that worked yesterday. Only
new choices skip it, such as add, or an update that would otherwise pick it.
A third state exists only for hub administrators: a quarantined version is hidden from everyone, including projects that locked it, while it is investigated (chapter 32). You will see that as the version being unavailable.
Chapter 18 shows how publishers deprecate and yank.
Which hub you are searching
search and info read exactly one hub: the one your default login points
at, or the public hub if you have no login. Unlike add, they do not fall
back from a private hub to the public one. To look at another hub, name it:
gritpack search throttle --from get.gritpack.org
gritpack info gritpack --from get.gritpack.org
--from reads only that hub, for this one command, whatever your logins say.
Chapter 9 explains hubs and sources in full.
What just happened
search found packages by words and narrowed them by kind, platform and
owner; info read one package in detail, version by version. Deprecation is
advice you can see, a yank keeps new projects away without breaking old ones,
and both commands read one hub at a time.
You can stop here
If you can find what you need and judge whether to use it, you are done with this chapter.
Next
- Where packages come from when you have more than one hub: Hubs and sources.
- Optional: everything about JSON output, in Scripting with JSON.