Coming from Cargo, npm or Go
The commands you know, and their Gritpack counterparts
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
| Idea | Cargo | npm | Go | Gritpack |
|---|---|---|---|---|
| Where packages live | crates.io, or an alternate registry | the npm registry, or a private one | proxy.golang.org, or a private proxy | a hub: get.gritpack.org, or your team's private hub |
| Who may publish a name | the crate's owners | the package's owners, or the scope's organisation | whoever controls the module path's repository | the account that owns the name or its scope |
| Private packages | a private registry | private packages or a private registry | GOPRIVATE and a private proxy | a private hub; everyone with a login can read everything on it |
| Lock file | Cargo.lock | package-lock.json | go.sum | your tool's own lock file, and gritpack.lock for native packages |
| Credential | a token in credentials.toml | _authToken in .npmrc | .netrc or GOAUTH | a login that lasts 30 days; tools get tokens that last minutes |
| Fixing a bad version | yank | deprecate, or unpublish within a time limit | retract | publish a new version; yank or deprecate the old one |
From Cargo
| You run | With your hub | For Gritpack's own packages |
|---|---|---|
cargo login | gritpack login, then gritpack setup once per project | gritpack login |
edit ~/.cargo/config.toml for a registry | gritpack setup or gritpack cargo setup | not needed |
cargo add serde | unchanged; cargo add name --registry gritpack for a private crate | gritpack add name |
cargo update | unchanged | gritpack update |
cargo build --locked | unchanged | gritpack sync --frozen |
cargo tree | unchanged | gritpack list, gritpack why name |
cargo search name | cargo search name --registry gritpack, or gritpack search name --ecosystem cargo | gritpack search name |
cargo info name | gritpack info name --ecosystem cargo | gritpack info name |
cargo publish | gritpack publish | gritpack publish |
cargo yank | unchanged, with --registry gritpack | gritpack package yank name@version |
cargo owner | not supported; an administrator manages ownership | gritpack 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 run | With your hub | For Gritpack's own packages |
|---|---|---|
npm login | gritpack login; never npm login against the hub | gritpack login |
npm config set @ada:registry ... | gritpack setup, or gritpack npm setup --scope @ada | not needed |
npm install | gritpack npm run --registry URL --profile NAME -- install | gritpack add, gritpack sync |
npm ci | gritpack npm run ... -- ci | gritpack sync --frozen |
npm outdated | gritpack npm run ... -- outdated | gritpack outdated |
npm ls, npm explain | unchanged | gritpack list, gritpack why name |
npm view name | gritpack npm run ... -- view name | gritpack info name |
npm publish | gritpack publish | gritpack publish |
npm deprecate | gritpack npm run ... -- deprecate | gritpack package deprecate name@version "message" |
npm dist-tag | gritpack npm run ... -- dist-tag | — |
npm unpublish | not possible; publish a new version | not possible; gritpack package yank |
npm install -g tool | — | gritpack install tool, for applications published to a hub |
npm run build, npm test | unchanged, 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 run | With your hub | For Gritpack's own packages |
|---|---|---|
go env -w GOPROXY=... GONOSUMDB=... | gritpack setup, or gritpack go setup --private-prefix example.com/ada | not needed |
a .netrc entry for the proxy | not needed: GOAUTH asks Gritpack for a token | not needed |
go get module@v1.2.3 | unchanged | gritpack add name 1.2.3 |
go mod tidy, go build | unchanged | gritpack sync |
go list -m -versions module | unchanged | gritpack info name |
push a tag v1.2.3 | gritpack publish --version v1.2.3 --published-at TIME | gritpack publish |
retract in go.mod | unchanged | gritpack 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.
- Run
gritpack setupin one crate and publish it withgritpack publish. - In one consumer, add
registry = "gritpack"to that dependency. crates.io still serves everything else. - 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.
- Claim your scope on the hub, or have it assigned to you.
- Run
gritpack setupin one package and publish it. - In consumers, the
@scope:registry=line routes that scope to the hub; usegritpack npm run -- installlocally and in CI.
To undo: remove the @scope:registry= line from .npmrc.
A Go team.
- Run
gritpack go setup --private-prefixfor your private path prefix. The comma fallback keeps proxy.golang.org for everything else. - 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.
- Turn one library into a package: a
gritpack.toml, and agritpack-c.tomlif consumers should get CMake and pkg-config files. - 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
- Start with the chapter for your tool: Rust and Cargo, npm, Go modules or C and C++.
- Optional deep dive: Publishing step by step,
for what happens inside
gritpack publish.