Skip to main content
The current public filepacks compare command performs structural comparison only. It compares the two manifests by path, size, and hash. That is enough to answer a practical review question: did any packaged file change between the baseline and the candidate?

​
What structural comparison means

Structural comparison answers one question: did any packaged file change between two runs? It classifies differences as:
  • added: a file exists in the candidate but not the baseline
  • removed: a file exists in the baseline but not the candidate
  • changed: same path in both artifacts but different size or hash
The comparison is manifest-driven. No manual unpack step is required, and the rules are the same across environments because paths are normalized and manifest entries are sorted.

​
Why this is useful in practice

Ad hoc directory comparison depends on filesystem state and tool choice. Manifest-based comparison has a fixed input format, fixed comparison rules, and a stable exit code. That makes compare a reliable primitive for:
  • detecting regressions between baseline and candidate runs
  • verifying that agent or eval output did not change unexpectedly
  • gating CI jobs on structural equivalence
  • producing a diff log for human review

​
Reading the output

Typical output:
  • exit 0: no differences
  • exit 20: one or more files were added, removed, or changed
  • exit 1: usage or file/path error
The per-file lines are meant to drive the next review step. They tell you which paths to inspect, not whether the change is desirable.

​
A practical review loop

  1. inspect the candidate if you need a quick summary.
  2. verify the candidate before using it as evidence.
  3. compare baseline vs candidate.
  4. Review the reported paths in the original output or your own tooling.
  5. If the change is accepted, store the new .fpk file as the next baseline explicitly.

​
What compare does not tell you

compare does not tell you whether a change is semantically good, bad, or expected. It only tells you that the packaged files changed structurally. That is why filepacks works well as evidence infrastructure:
  • humans can use the path list to review the right files
  • agents can use the exit code to decide whether to escalate or continue
  • CI can preserve the changed artifact for later inspection

​
Core API

@filepacks/core compare() returns a structural result object with:
  • mode: 'structural'
  • ok
  • summary.added
  • summary.removed
  • summary.changed
  • added[]
  • removed[]
  • changed[]
Each changed file includes both left and right size/hash values.

​
See also

  1. CLI — Compare for command details.
  2. CLI workflows for repeatable review patterns.
  3. Agent workflows for baseline/candidate handoff in repeated runs.