Schematic Schematic Pup docs
Schematic website
Help

Source and commits#

Pup checks supertests against Git commits. The commit object ID gives each result a familiar, immutable source identity that remains meaningful when branches move.

What source Pup sends#

pup repo link is the consent boundary before source leaves your computer. Pup sends eligible regular files from the selected immutable Git tree. It does not traverse parent directories or upload symbolic links.

Eligible content typically includes:

  • Source code and supertests
  • Dependency manifests and lockfiles
  • Build and language configuration
  • Schemas, templates, and source fixtures used by the code

Pup sends the selected commit identity and the eligible contents required to understand and check it. It does not push to a Git remote or send every branch, remote-tracking reference, reflog, or commit in the repository’s history.

Pup advertises a complete manifest of eligible paths, byte lengths, executable bits, and content hashes. It then sends only content Schematic does not already have. Interrupted transfers resume from the server’s verified byte position, and the commit is not ready until every received object and the complete tree identity have been verified.

Exclusion rules#

Pup applies these rules before source is sent:

  1. Entries matched by .pupignore are excluded.
  2. A symbolic link, Git submodule, or other nonregular Git entry that is not excluded stops preparation with an actionable error. Pup never omits it silently.
  3. Untracked files matched by .gitignore do not enter a temporary Pup commit.
  4. Individual files larger than 10 MiB are excluded and reported.

.pupignore uses Git ignore syntax. Put it at the linked root:

.pupignore
# Local credentials and private fixtures
.env*
secrets/
fixtures/customer-data/

# Generated output not required for checking
tmp/
coverage/

Tracked files remain part of their Git commit even when they match .gitignore. Use .pupignore when a tracked path must not be sent to Schematic.

If the project contains a symlink or submodule that checking does not require, add that path to .pupignore. Otherwise replace it with regular committed content before retrying. This makes every omission explicit in the same commit whose source is checked.

Sensitive files: Pup cannot determine whether every source file or fixture is safe to send. Keep credentials and private data in excluded files. Review .pupignore before linking a repository.

Checked-out commits#

After linking, Pup watches the commit checked out in that repository. When a commit, checkout, merge, rebase, reset, or branch switch moves HEAD to an unseen commit, Pup begins preparing its eligible source in the background.

Pup does not send every local branch. You can select another locally available commit explicitly with --commit <git-revision> on pup check.

Preparing a commit does not run git push, modify a remote, or change any Git references.

Temporary Pup commits#

When the repository has uncommitted changes, Pup never silently ignores them and checks HEAD. It can instead create a temporary Pup commit containing the current tracked changes and eligible untracked files.

The first time this happens in an interactive terminal, Pup asks for permission and remembers the answer for that linked repository. The temporary Pup commit is created without changing your branch, HEAD, working files, or Git index.

Pup retains it under a hidden Git reference, so its object ID remains usable with ordinary Git commands:

Terminal
$ git show 4e92c1a
$ git diff 4e92c1a
$ git restore --source=4e92c1a -- path/to/file
$ git branch recovered-work 4e92c1a

The final command promotes the temporary Pup commit to a normal local branch. A temporary Pup commit is not a complete backup of ignored or excluded files.

Pass --dirty to authorize a temporary Pup commit for one command without a prompt. Pass --commit <git-revision> to check a specific commit and ignore current uncommitted changes.

Checks and commit identity#

One check evaluates one supertest against one commit. Later edits or branch movement cannot alter the source or result for that check.

If the same commit, supertest, and checking options are selected again, Pup reuses the existing check. A different commit receives a distinct check even when Schematic can safely reuse work internally.

How Schematic processes source#

Eligible content is transmitted to the Schematic service over an encrypted connection and stored for asynchronous processing. Contact Schematic support before linking if your organization has specific residency, retention, or deletion requirements.