Coming from Cargo, npm or Go

The commands you know, and their Gritpack counterparts

Chapter 34 of 34Current for Gritpack 1.2.63Source: docs/guide/34-coming-from-cargo-npm-go.md

You already know a package manager well, and you would like to know where your habits carry over and where they do not. This chapter maps the commands you use every day to their Gritpack counterparts, explains the few places where Gritpack behaves differently and why, and ends with a way to move a team over gradually, with a way back at every step.

What you will be able to do

  • find the Gritpack counterpart of a Cargo, npm or Go command quickly;
  • tell when to keep using your own tool and when to use gritpack;
  • explain to your team what changes and what does not;
  • move one project at a time, and undo each step if you need to.

Two ways Gritpack meets you

Gritpack works with your tool in two different ways, and it helps to keep them apart.

Behind your tool. For Rust, npm and Go, the hub acts as a registry your tool already understands: a Cargo registry, an npm registry, a Go module proxy. You keep running cargo, npm and go. Gritpack sets them up, supplies short-lived credentials, and publishes for you. Chapters 10, 11 and 12 teach this.

On its own. For C and C++, and for any files that have no package manager of their own, Gritpack is the package manager: gritpack add, gritpack sync, gritpack.lock. The commands are deliberately close to the ones you know. Chapters 5 to 7 and 13 teach this.

Applications are a third case: gritpack install puts a command-line program in your PATH, like cargo install, npm install -g or go install, but it installs a published, ready-built package rather than building from source (Installing applications).

The ideas, side by side

IdeaCargonpmGoGritpack
Where packages livecrates.io, or an alternate registrythe npm registry, or a private oneproxy.golang.org, or a private proxya hub: get.gritpack.org, or your team's private hub
Who may publish a namethe crate's ownersthe package's owners, or the scope's organisationwhoever controls the module path's repositorythe account that owns the name or its scope
Private packagesa private registryprivate packages or a private registryGOPRIVATE and a private proxya private hub; everyone with a login can read everything on it
Lock fileCargo.lockpackage-lock.jsongo.sumyour tool's own lock file, and gritpack.lock for native packages
Credentiala token in credentials.toml_authToken in .npmrc.netrc or GOAUTHa login that lasts 30 days; tools get tokens that last minutes
Fixing a bad versionyankdeprecate, or unpublish within a time limitretractpublish a new version; yank or deprecate the old one

From Cargo

You runWith your hubFor Gritpack's own packages
cargo logingritpack login, then gritpack setup once per projectgritpack login
edit ~/.cargo/config.toml for a registrygritpack setup or gritpack cargo setupnot needed
cargo add serdeunchanged; cargo add name --registry gritpack for a private crategritpack add name
cargo updateunchangedgritpack update
cargo build --lockedunchangedgritpack sync --frozen
cargo treeunchangedgritpack list, gritpack why name
cargo search namecargo search name --registry gritpack, or gritpack search name --ecosystem cargogritpack search name
cargo info namegritpack info name --ecosystem cargogritpack info name
cargo publishgritpack publishgritpack publish
cargo yankunchanged, with --registry gritpackgritpack package yank name@version
cargo ownernot supported; an administrator manages ownershipgritpack scope claim, and your hub's administrator
cargo install tool—gritpack install tool, for applications published to a hub

Plain cargo publish --registry gritpack reaches the same registry, but a hub that keeps signed evidence for every publication accepts new versions only through gritpack publish. That command runs cargo package for you, so Cargo still builds and checks the crate.

From npm

You runWith your hubFor Gritpack's own packages
npm logingritpack login; never npm login against the hubgritpack login
npm config set @ada:registry ...gritpack setup, or gritpack npm setup --scope @adanot needed
npm installgritpack npm run --registry URL --profile NAME -- installgritpack add, gritpack sync
npm cigritpack npm run ... -- cigritpack sync --frozen
npm outdatedgritpack npm run ... -- outdatedgritpack outdated
npm ls, npm explainunchangedgritpack list, gritpack why name
npm view namegritpack npm run ... -- view namegritpack info name
npm publishgritpack publishgritpack publish
npm deprecategritpack npm run ... -- deprecategritpack package deprecate name@version "message"
npm dist-taggritpack npm run ... -- dist-tag—
npm unpublishnot possible; publish a new versionnot possible; gritpack package yank
npm install -g tool—gritpack install tool, for applications published to a hub
npm run build, npm testunchanged, with plain npm—

The bridge gritpack npm run refuses commands such as test, run and exec while it holds a credential, and turns install scripts off. Run your scripts with plain npm. Like npm, gritpack add name 1.2.3 saves the compatible range ^1.2.3; write =1.2.3 to pin exactly.

From Go

You runWith your hubFor Gritpack's own packages
go env -w GOPROXY=... GONOSUMDB=...gritpack setup, or gritpack go setup --private-prefix example.com/adanot needed
a .netrc entry for the proxynot needed: GOAUTH asks Gritpack for a tokennot needed
go get module@v1.2.3unchangedgritpack add name 1.2.3
go mod tidy, go buildunchangedgritpack sync
go list -m -versions moduleunchangedgritpack info name
push a tag v1.2.3gritpack publish --version v1.2.3 --published-at TIMEgritpack publish
retract in go.modunchangedgritpack package yank name@version
go install tool@latest—gritpack install tool

A Go module is published by an explicit command, not by pushing a tag: the hub does not read your repository. The publication time is part of the command so the same command always produces the same module version.

What is different, and why

The hub is the privacy boundary. There are no private packages on a public hub and no per-package access lists. A private hub is private as a whole: everyone it lets in can read everything on it. This keeps the question "who can see this?" to one answer per hub.

Versions never change, and never disappear. No registry here lets you overwrite a version or unpublish it. A bad version is followed by a good one, and the bad one is yanked (new projects stop choosing it, existing locks keep working) or deprecated (everyone sees a warning). See After publishing.

Publishing is a transaction. gritpack publish checks everything locally and with the hub first, then makes the new versions visible in one step, all or none, even when they are in different languages. It leaves a signed receipt saying who published what and when (Evidence and receipts). Your ecosystem's own publish command is a single-package path and, on hubs that keep evidence, is refused.

Every new version is documented. A hub refuses a new version without a README of at least 100 words and a licence, unless the publisher gives a reason in words of their own (README and licence).

Names are owned. An unscoped name belongs to the account that first publishes it, in every ecosystem. A scope such as @ada is claimed once and then covers npm packages and native packages alike (Names, scopes and owners).

Credentials are short-lived. You log in once per hub, for 30 days. Cargo, npm and Go get tokens that live for minutes, made when they need them. Nothing long-lived is written to .npmrc, Cargo's credentials file or .netrc.

One lock across languages, for native packages. gritpack.lock can hold a C library, a Rust-dialect package and anything else together. Your ecosystem's own lock file still governs its own dependencies.

None of this makes Cargo, npm or Go worse at what they do. They build, test and resolve; Gritpack keeps the packages, their owners and the record of who published what.

Moving over without a flag day

Move one project, or one package, at a time. Each step below can be undone, and the public registries stay in use the whole time.

A Rust team.

  1. Run gritpack setup in one crate and publish it with gritpack publish.
  2. In one consumer, add registry = "gritpack" to that dependency. crates.io still serves everything else.
  3. Move the next crate when the first has been through a release.

To undo: point the dependency back where it was and delete the [registries.gritpack] entry. Nothing on crates.io changed.

A JavaScript team.

  1. Claim your scope on the hub, or have it assigned to you.
  2. Run gritpack setup in one package and publish it.
  3. In consumers, the @scope:registry= line routes that scope to the hub; use gritpack npm run -- install locally and in CI.

To undo: remove the @scope:registry= line from .npmrc.

A Go team.

  1. Run gritpack go setup --private-prefix for your private path prefix. The comma fallback keeps proxy.golang.org for everything else.
  2. Publish one module version with gritpack publish --version ... --published-at ....

To undo: go env -u GOPROXY GONOSUMDB GOAUTH.

A folder of C and C++ archives.

  1. Turn one library into a package: a gritpack.toml, and a gritpack-c.toml if consumers should get CMake and pkg-config files.
  2. Publish it, and switch one consumer to gritpack add. Leave the old folder in place until every consumer has moved.

To undo: point the consumer's build back at the folder.

What just happened

  • The everyday commands of Cargo, npm and Go each found a counterpart: usually the same command, sometimes gritpack.
  • The differences come down to a few rules: the hub is the privacy boundary, versions never change, publishing is a transaction with a receipt, names are owned, and credentials are short-lived.
  • Each language has a gradual path in, with a way back at every step.

You can stop here

If you came to see whether your habits carry over, you have your answer.

Next