Finding packages

search and info, deprecated and yanked versions

Chapter 8 of 34Current for Gritpack 1.2.63Source: docs/guide/08-finding-packages.md

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:

FieldMeaning
ecosystemnative for Gritpack packages, cargo for crates in the hub's Cargo registry
scorehow well it matched; an exact name match scores highest
dialectwhat kind of package it is
variantshow many variants were published, across versions and platforms
after the dashthe 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

OptionKeeps only
--ecosystem native or cargoone ecosystem
--dialect c/c23that kind of package
--encoding source/utf8that encoding
--target x86_64-unknown-linux-gnubuilds for that platform
--version '^1.2'packages with a version in that range
--owner <account-id>packages published by that account
--limit 10at 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