Keeping up to date

outdated, update, upgrade, list, why, verify and doctor

Chapter 7 of 34Current for Gritpack 1.2.63Source: docs/guide/07-keeping-up-to-date.md

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 list and why;
  • check a project with verify, and diagnose it with doctor.

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:

FieldMeaning
currentthe version in your lock now
wantedthe newest version your requirement (^1.0.0) already allows
latestthe 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.

updateupgrade
Changes gritpack.tomlnoyes, raises requirements
Changes gritpack.lockyesyes
Can cross a major versionnoyes
Moves transitive packagesyes, within what their parents acceptyes, within what their parents accept

From npm. update is npm update. upgrade is what you would do with npm install name@latest for each dependency.

From Cargo. update is cargo update. upgrade is like cargo upgrade from cargo-edit, or editing Cargo.toml by 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:

LayerChecks
projectwhat kind of project this is
profile, provideryour login profile, and that its credential can be read
identitythe hub accepts the credential and the account is active
hubthe hub answers, and which repository it is
localmanifest, lock, installed packages, and that they agree
ecosystemCargo, 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

  1. gritpack outdated now and then, or in a scheduled CI job.
  2. gritpack update for fixes; build and test; commit gritpack.lock.
  3. gritpack upgrade <name> for a new major version, one at a time; read the package's notes; build and test; commit both files.
  4. gritpack sync --frozen and gritpack verify in CI.
  5. gritpack doctor when 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