Skip to Content
Getting Started

Compatibility and versioning

What xgrep keeps stable across releases — the CLI, the output schemas, and the rule format — and what deliberately keeps evolving.

xgrep follows semantic versioning. Within a major version, the interfaces below are stable: you can build a pipeline, a dashboard, or a CI gate on them and trust that a minor or patch upgrade will not break it. A breaking change to any of them happens only in a new major version and is called out in the release notes.

The one thing that is not frozen is the set of findings itself — and that is deliberate. See What keeps evolving below.

Exit codes

The exit-code contract is stable within a major version: 0 when the run completed and the policy passed, a distinct non-zero code when findings breach the configured gate, and a separate non-zero code for an execution error. Scripts may branch on these.

Output formats

  • JSON (--json) carries a schema_version field. Additive changes (a new field) bump the minor schema version; a breaking change to an existing field's shape or meaning bumps the major schema version and is announced. Consumers should pin on the major and ignore unknown fields, so a minor bump never breaks a reader. A machine-readable JSON Schema is published for validation.
  • SARIF output targets SARIF 2.1.0.
  • GitLab SAST output targets schema 15.0.6.

Fields are added, not repurposed. A field present in a 1.x release stays present with the same meaning for the rest of the 1.x line.

Rule format

xgrep reads Semgrep-compatible rule syntax, and that syntax is stable: rules you write against a 1.x release keep working across the 1.x line. xgrep-specific extensions are additive — they add capability without changing how an existing rule behaves. See Semgrep compatibility.

Command-line interface

The xgrep command and flag surface is stable within a major version. When a flag is superseded it is deprecated, not removed: it keeps working as a no-op or an alias, emits a deprecation notice, and is only dropped in a future major version. A script that worked on 1.0 keeps working across the 1.x line. See the CLI reference.

What keeps evolving

xgrep is a security scanner, and its job is to get more accurate over time. So the set of findings a scan reports is not part of the compatibility contract: rules are added and refined and the engine's analysis improves, which means a later 1.x release can legitimately report a finding an earlier one missed, or stop reporting one that was noise. That is the product working as intended, not a breaking change — freezing it would freeze the accuracy improvements that are the point of the tool. Finding content evolves; the formats and interfaces that carry it stay stable as described above.

Human-readable message text is likewise not an interface — do not parse it. Use the JSON/SARIF fields.

Last updated on

On this page