Check commands#

A check evaluates one supertest against one Git commit. A file or directory selection creates or reuses one independent check for every supertest Pup discovers.

pup check#

Check every supertest in the linked repository:

$ pup check

Bare pup check checks the entire linked repository. You can instead select a file, directory, or one named supertest:

pup check [path-or-selector] [--problems] [--prove] [--commit <git-revision> | --dirty] [--wait]

$ pup check supertests/serialization.rs
text-tools · a81d7c2 · supertests/serialization.rs

● round_trip_preserves_value    · checking · ref 43
● encoded_length_matches_header · checking · ref 44

$ pup check supertests/serialization.py
text-tools · a81d7c2 · supertests/serialization.py

● round_trip_preserves_value    · checking · ref 43
● encoded_length_matches_header · checking · ref 44

$ pup check supertests/serialization.rb
text-tools · a81d7c2 · supertests/serialization.rb

● round_trip_preserves_value    · checking · ref 43
● encoded_length_matches_header · checking · ref 44

The file selector finds both declarations and gives each supertest its own row. The trailing reference identifies that exact attempt within the repository.

By default, Pup checks the current commit. If there are uncommitted changes, it asks whether to include them. Pass --dirty to answer yes without a prompt, or --commit to select a particular local commit. Source and commits explains the underlying behavior.

Select supertests#

$ pup check supertests/serialization.rs
$ pup check supertests/payments/
$ pup check 'supertests/serialization.rs::round_trip_preserves_value'
$ pup check

$ pup check supertests/serialization.py
$ pup check supertests/payments/
$ pup check 'supertests/serialization.py::round_trip_preserves_value'
$ pup check

$ pup check supertests/serialization.rb
$ pup check supertests/payments/
$ pup check 'supertests/serialization.rb::round_trip_preserves_value'
$ pup check

File selectors check every supertest in that file. Directory selectors discover supertests recursively. Paths resolve from the current directory, so . selects the current directory and its descendants. A named file::supertest selector checks one declaration.

With shell completion installed, Pup completes paths and locally discoverable supertest names after ::.

Recheck Problems#

After changing the source, recheck problematic supertests from the latest matching check:

$ pup check --problems

Limit that selection to a file or directory when useful:

$ pup check supertests/serialization.rs --problems

$ pup check supertests/serialization.py --problems

$ pup check supertests/serialization.rb --problems

Add --wait if you want to follow the new checks in the same terminal.

--problems selects supertests with reported Problems or confirmed failures in the latest matching pup check, then checks them against the source Pup would normally select now. A new commit therefore creates new attempts with new references. If an existing attempt already meets the request, Pup reuses it.

For one particular supertest, use the canonical file::supertest selector shown by focused status.

Wait for results#

Without --wait, Pup starts or reuses the checks, prints their accepted rows, and exits while unfinished work continues remotely. Pass --wait to keep the terminal attached. Finished rows remain visible, active rows update in place, and each completed row settles into the same table.

After an interactive wait lasting at least five seconds, Pup rings the terminal bell when the checks finish.

Interrupting a wait detaches the terminal but does not cancel remote work. Exit status 0 means the command operated successfully, regardless of the check results.

Checks waiting for source preparation#

If Schematic is still preparing the selected source, rows begin as pending and advance automatically:

$ pup check supertests/
text-tools · c24f901 · supertests/

○ round_trip_preserves_value    · pending · ref 47
○ encoded_length_matches_header · pending · ref 48

When Pup reuses a check#

Pup reuses an existing attempt when it already meets the request for the same supertest and commit. Reuse happens independently for each row, so a full check can reuse a targeted result from the same commit. Canceled and Error checks can be retried.

Request proof#

Pass --prove when you need Pup to establish that the selected claims hold for the commit:

$ pup check --prove

A proof check may finish as verified, failed, a Problem count, or inconclusive. 0 problems is a standard-check result and does not satisfy a later --prove request.

pup check status#

Observe the latest activity or focus one exact attempt:

pup check status [--wait]
pup check status <path-or-selector> [--wait] [--browse]
pup check status <reference> [--wait] [--browse]

With no argument, Pup shows the rows from the most recent pup check in the current repository. When that invocation contains one supertest, Pup uses the focused view and includes any Problems, evidence, or operational error for that attempt.

An explicit path or selector instead shows every matching supertest in the current checked-out commit without starting new checks. Supertests without an attempt for that commit appear as not checked. Paths resolve from the current directory, so pup check status . covers the whole repository when run at its root and only the current subtree when run from a nested directory.

For several supertests, Pup shows the latest state for the selected commit and the immediately preceding attempt when one exists:

$ pup check status .
text-tools · c24f901 · .

  SUPERTEST                       · CURRENT     · REF  ←  PREVIOUS ATTEMPT
✓ round_trip_preserves_value      · 0 problems  ·  49  ←  × failed     · a81d7c2
! encoded_length_matches_header   · 1 problem   ·  50  ←  ✓ 0 problems · a81d7c2
● decoding_rejects_trailing_bytes · checking    ·  51
○ empty_payload_is_rejected       · not checked ·      ←  ! 1 problem  · a81d7c2

REF identifies the current attempt. The compact previous-attempt comparison omits its reference; focus the supertest to explore that history.

Focus one supertest or attempt#

Use a named supertest selector or reference to see attempts for one supertest:

$ pup check status 43
text-tools · supertests/serialization.rs::round_trip_preserves_value

    COMMIT  · STATUS     · WHEN    · REF
  ✓ c24f901 · 0 problems · 12s ago ·  49
    … 3 matching attempts omitted …
  ✓ b902fd1 · 0 problems · 2d ago  ·  44
› × a81d7c2 · failed     · 3d ago  ·  43
  ✓ 41cef29 · 0 problems · 6d ago  ·  38

$ pup check status 43
text-tools · supertests/serialization.py::round_trip_preserves_value

    COMMIT  · STATUS     · WHEN    · REF
  ✓ c24f901 · 0 problems · 12s ago ·  49
    … 3 matching attempts omitted …
  ✓ b902fd1 · 0 problems · 2d ago  ·  44
› × a81d7c2 · failed     · 3d ago  ·  43
  ✓ 41cef29 · 0 problems · 6d ago  ·  38

$ pup check status 43
text-tools · supertests/serialization.rb::round_trip_preserves_value

    COMMIT  · STATUS     · WHEN    · REF
  ✓ c24f901 · 0 problems · 12s ago ·  49
    … 3 matching attempts omitted …
  ✓ b902fd1 · 0 problems · 2d ago  ·  44
› × a81d7c2 · failed     · 3d ago  ·  43
  ✓ 41cef29 · 0 problems · 6d ago  ·  38

The bold row and violet › mark the attempt in focus. REF is a short, repository-scoped reference for opening or canceling that exact attempt. Pup may summarize a long stretch of matching successful attempts while keeping the preceding Problem, failure, or other result visible.

Add --browse when you want to move through the complete history for one supertest. Use the arrow keys or j and k; the selected attempt’s Problems, evidence, or operational error update below the table as you move. If the details do not fit, press Enter to expand them, then Enter or Escape to return. Press q, Escape, or Ctrl-C to close the attempt list.

In a focused view, Problems, their evidence, and operational errors for the selected attempt follow the table:

Problem P1
  Normalization is not idempotent
  collapse_spaces replaces only one pair of spaces per call.

Confirmed counterexample
  text   = "hello   world"
  once   = "hello  world"
  twice  = "hello world"

Add --wait to follow an active attempt until it finishes. Pup keeps the same focused history visible while the selected row and its evidence update in place.

Problems before checking completes#

Pup may report a Problem while a check is still checking. A completed standard check displays the number of Problems it found. Only a confirmed counterexample produces failed.

Check states#

Check results#

Routine tables show the result rather than displaying complete in a separate column. The result does not change the command’s process status.

pup check cancel#

Cancel Pending, Queued, or Checking rows:

pup check cancel
pup check cancel <path-or-selector>
pup check cancel <reference>

With no argument, Pup cancels active rows from the most recent check invocation in the repository. A selector targets active matching rows from the latest invocation containing that selector. A reference targets one exact attempt.

$ pup check cancel 43
○ round_trip_preserves_value · canceled · ref 43

Cancellation preserves the check, commit association, Problems, and information already produced. If a row is already terminal, Pup reports its state and changes nothing. A canceled or errored check is not reused.