Keeping up to date
outdated, update, upgrade, list, why, verify and doctor
A lock keeps everything still, which is what you want until a fix or a new feature is published. Then you want to move, on purpose, and know exactly what moved. This chapter shows how to see what could change, move within the ranges you already accept, move beyond them, and check that what is on disk is still what the lock says.
What you will be able to do
- see which dependencies have newer versions, with
outdated; - take compatible fixes with
update, without editing anything; - move to a new major version with
upgrade; - explain what you have, with
listandwhy; - check a project with
verify, and diagnose it withdoctor.
The examples continue the project from the last two chapters. It depends on
@ada/greet, which depends on @ada/strings. At the start, the lock holds
@ada/greet 1.0.0 and @ada/strings 1.0.0, and gritpack.toml asks for
"@ada/greet" = "^1.0.0".
What you have: list and why
$ gritpack list
@ada/greet 1.0.0 dialect=c/c23 direct source=https://packages.example.com:443 dependencies=@ada/strings
@ada/strings 1.0.0 dialect=c/c23 transitive source=https://packages.example.com:443 dependencies=-
list reads the lock and prints one line per package: version, variant,
whether you asked for it (direct) or something else did (transitive), the
hub it came from, and what it depends on.
why explains one package by the shortest chain from a direct dependency:
$ gritpack why @ada/strings
@ada/greet -> @ada/strings
$ gritpack why @ada/greet
@ada/greet
@ada/strings is here because @ada/greet needs it. @ada/greet is here
because you asked for it. Neither command contacts a hub.
What could move: outdated
The publisher of @ada/strings released 1.1.0. Ask what that means for you:
$ gritpack outdated
@ada/greet current=1.0.0 wanted=1.0.0 latest=1.0.0 update=false upgrade=false
Nothing, as far as outdated can see: it lists your direct dependencies only,
and @ada/greet has no newer version. @ada/strings is a dependency of a
dependency, so it moves when you update.
Within your ranges: update
$ gritpack update
updated 2 packages status=changed
$ gritpack list
@ada/greet 1.0.0 dialect=c/c23 direct source=https://packages.example.com:443 dependencies=@ada/strings
@ada/strings 1.1.0 dialect=c/c23 transitive source=https://packages.example.com:443 dependencies=-
update resolved again, preferring the newest versions the requirements
allow. @ada/greet asks for ^1.0 of @ada/strings, so 1.1.0 was allowed and
taken. Your gritpack.toml did not change. Only the lock and packages/
moved. Run it again and there is nothing left to do:
$ gritpack update
updated 2 packages status=unchanged
Now the publisher of @ada/greet releases 1.0.1, a fix, and 2.0.0, which
changes its interface:
$ gritpack outdated
@ada/greet current=1.0.0 wanted=1.0.1 latest=2.0.0 update=true upgrade=true
Three versions, three meanings:
| Field | Meaning |
|---|---|
current | the version in your lock now |
wanted | the newest version your requirement (^1.0.0) already allows |
latest | the newest version published, whatever your requirement says |
update=true says current can move to wanted without editing anything.
upgrade=true says something newer still exists, and reaching it means
changing your requirement. outdated itself changes nothing.
Name a package to update only that one (and what it needs):
$ gritpack update @ada/greet
updated 2 packages status=changed
$ gritpack list
@ada/greet 1.0.1 dialect=c/c23 direct source=https://packages.example.com:443 dependencies=@ada/strings
@ada/strings 1.1.0 dialect=c/c23 transitive source=https://packages.example.com:443 dependencies=-
gritpack.toml still says ^1.0.0; 1.0.1 is inside that range.
update never leaves the hub a package was locked from. If that hub no
longer offers the package, it stops and says so instead of looking elsewhere
(chapter 9).
Beyond your ranges: upgrade
outdated still says upgrade=true:
$ gritpack outdated
@ada/greet current=1.0.1 wanted=1.0.1 latest=2.0.0 update=false upgrade=true
A new major version may break your code, so Gritpack does not take it unless
you ask. upgrade raises the requirement in gritpack.toml to the newest
version and installs it:
$ gritpack upgrade @ada/greet
upgraded 1 direct dependencies
$ head -2 gritpack.toml
[dependencies]
"@ada/greet" = "^2.0.0"
$ gritpack outdated
@ada/greet current=2.0.0 wanted=2.0.0 latest=2.0.0 update=false upgrade=false
With no package names, upgrade raises every direct dependency. Review the
change to gritpack.toml and gritpack.lock as you would any other change,
build, and commit both files together.
update | upgrade | |
|---|---|---|
Changes gritpack.toml | no | yes, raises requirements |
Changes gritpack.lock | yes | yes |
| Can cross a major version | no | yes |
| Moves transitive packages | yes, within what their parents accept | yes, within what their parents accept |
From npm.
updateisnpm update.upgradeis what you would do withnpm install name@latestfor each dependency.
From Cargo.
updateiscargo update.upgradeis likecargo upgradefrom cargo-edit, or editingCargo.tomlby hand.
Pinned versions
A dependency pinned with =1.0.0 never moves with update. outdated
shows that with wanted equal to current:
$ gritpack outdated
@ada/greet current=1.0.0 wanted=1.0.0 latest=2.0.0 update=false upgrade=true
upgrade replaces the pin with a compatible range on the newest version.
Is it still right: verify
verify checks the project strictly, without contacting a hub: the manifest
agrees with the lock, and every installed file has the size, digest and
executable bit the lock's packages say it should.
$ gritpack verify
verified 2 packages and 8 files universe=8efb3ff135ddaf86907acaa20815fcf8a31be1f95aef343cd66629f600d37b4b
The universe is one digest for the whole installed set. Two machines with
the same universe have the same packages, byte for byte.
On any difference, verify stops at the first one and exits with a non-zero
code, which makes it a good last step in CI:
$ gritpack verify
installed file is stale or missing: ./packages/@ada/greet/src/greet.c
That exit code is 7, "integrity". gritpack sync repairs it.
What is wrong: doctor
verify gives a verdict. doctor gives a diagnosis: it checks each layer of
your setup in order and says which one fails, with the command that fixes it.
$ gritpack doctor
PASS project — detected native at /home/ada/hello
PASS profile — profile=work provider=file
PASS provider — credential material resolved
PASS identity — account=01a1e866-03d9-7440-9677-13a172f2c676 email=ada@example.com status=Active
PASS hub — repository=550e8400-e29b-41d4-a716-446655440000 endpoint=https://packages.example.com:443
PASS local — workspace: workspace directory exists
PASS local — manifest: 1 direct dependencies
PASS local — lock: lock v4 with 2 packages
FAIL local — installed-universe: installed file is stale or missing: /home/ada/hello/packages/@ada/greet/src/greet.c
repair: gritpack sync
FAIL local — consistency: installed file is stale or missing: /home/ada/hello/packages/@ada/greet/src/greet.c
repair: gritpack sync
...
doctor found unhealthy project state
The layers, top to bottom:
| Layer | Checks |
|---|---|
project | what kind of project this is |
profile, provider | your login profile, and that its credential can be read |
identity | the hub accepts the credential and the account is active |
hub | the hub answers, and which repository it is |
local | manifest, lock, installed packages, and that they agree |
ecosystem | Cargo, npm or Go settings, for those projects |
Because doctor checks your login, its profile line fails when you have
none, even if the project only uses the public hub. That failure is expected;
the local lines still tell you about the project.
gritpack doctor --fix runs gritpack setup for the project first and then
checks. Setup only writes local configuration that can be undone, such as
Cargo or npm registry settings. It never logs in, publishes or changes anything
on a hub.
doctor --json gives the same checks as JSON, for scripts.
A routine that works
gritpack outdatednow and then, or in a scheduled CI job.gritpack updatefor fixes; build and test; commitgritpack.lock.gritpack upgrade <name>for a new major version, one at a time; read the package's notes; build and test; commit both files.gritpack sync --frozenandgritpack verifyin CI.gritpack doctorwhen anything looks odd.
What just happened
You moved a project forward twice, on purpose. update took the newest
versions your requirements already allowed, including a dependency of a
dependency, and left gritpack.toml alone. upgrade changed a requirement to
cross a major version. list, why and outdated told you where you stood,
verify proved the files on disk match the lock, and doctor pointed at the
layer that was wrong.
You can stop here
If you use packages in your own projects, Part One is nearly done. Two short chapters remain on finding packages and on which hub they come from.
Next
- Finding what to depend on: Finding packages.
- Optional: why a yanked or deprecated version behaves as it does, in After publishing.