Skip to main content
Use detect to review your package files, then generate an SBOM, audit dependencies, or check licenses. This reference covers Alpha version 0.5.0. For help with a command, run githits-scan <command> --help. For nested commands, use the full name, such as githits-scan sbom generate --help or githits-scan license check --help.

Common options

All six commands accept these output options: Diagnostics go to stderr. Reports go to stdout or the output file. For discovery and online analysis, use these options to control file selection: Online analysis requires GITHITS_API_TOKEN. Review what Scan uploads before running it. The HTTP API reference describes upload limits, quota, and how to interpret results.

Detect

Preview the package files Scan would upload, without a token or network connection:
Scan reads the selected files locally and prepares the same selection as an upload, including eligible workspace members. The inventory distinguishes selected files from candidates that won’t be uploaded. It lists skipped directory subtrees as patterns because their file counts are unknown. After reviewing the selection, save it to your configuration:
If no package files are selected, Scan exits 1. If Scan cannot prepare an upload, JSON inventory is still available with null upload_paths and an upload_error. The command then exits 2 for usage errors or 3 for I/O errors.

Generate an SBOM

Generate a dependency inventory in the format you need:
Scan submits one analysis job and writes the complete document returned by GitHits. Use --format to choose the output:

Audit dependencies

Check vulnerabilities, native lifecycle events such as deprecated or withdrawn releases, outdated and duplicate versions, and manifest/lockfile disagreements:
Audit requests native lifecycle report v3 automatically. Unignored findings, retained lifecycle warnings, and actionable incomplete checks return exit 1. Expected Git coverage limits appear as informational coverage notes and don’t fail an audit on their own. Lifecycle collection limits and checks that don’t apply also return exit 0 on their own; --details explains them. A clean audit covers the selected package files; it does not establish that an installed build is safe. Scan shows change suggestions when GitHits supplies them. It does not edit your dependencies. JSON and saved analyses retain findings even when the human-readable output omits details. To inspect an analysis offline, save it with --save-analysis. Compact audit --json output cannot be used as a saved analysis. Saved analyses use format 2, and saved explanations add audit_actionable_incomplete. audit --from-analysis reads only format 2. To replay an analysis saved by 0.4.0 (format 1), use Scan 0.4.0. Neither version migrates the other’s saved analyses. If GitHits returns an audit report version this Scan version doesn’t support, Scan exits 3 without writing output or resubmitting the job. To accept a reviewed advisory, add an [[audit.ignore]] entry to your configuration. Ignored findings stay visible with their reason and don’t cause exit 1 on their own.

Compare dependencies between revisions

Experimental. diff output is informational and can change between releases.
Compare direct and transitive dependencies between two Git revisions, or between a revision and the working tree:
Scan reads package files from each revision without changing your checkout and submits both sides as one analysis job. The report shows dependency changes per source, ownership, advisory changes, and direct upgrade evidence. Human-readable and Markdown output include changelog items and links returned by GitHits. JSON preserves the exact report from GitHits. diff requires Git and GITHITS_API_TOKEN, even when both sides are identical or empty. One comparison is charged at twice the quota weight of an audit. Both sides together share the upload limits of 256 files and 8,000,000 bytes including multipart framing. diff ignores githits-scan.toml. Use --exclude and --lockfiles-only to control the selection. Use --output-json and --output-markdown together to save both documents from the same analysis, or use either one alone. - writes to stdout for at most one of them. These options conflict with --format and -o, --output. Exit 0 means Scan produced a report, including when evidence is partial or unknown. It is not a policy pass.

Report licenses

Read license information without applying a policy:
You don’t need a license policy for this command. Exit 0 means Scan produced a report, even if license information is unknown or incomplete. Use license check to enforce a policy. The report separates reported licenses, publisher context, source observations, and coverage gaps. It does not give a policy verdict.

Check license policy

Configure a license policy, then check dependencies against it:
Without --sbom, Scan generates a CycloneDX JSON document online. With --sbom, it reads an existing document offline. Both forms require [licenses] in the selected configuration. Violations, missing or unrecognized licenses, and unresolved projects return exit 1. Scan warns on stderr when no components were evaluated or dependency resolution is incomplete. With --sbom, it also warns when the document has no githits:completeness property, because inventory completeness is unknown. Warnings appear even with --quiet and --json. They don’t change the verdict or exit code.

Offline replay

Inspect a saved analysis, read a license report, or check an SBOM without contacting the API. These commands need no token:
Use the matching saved document for each command: Replay uses the saved information. It does not refresh data from GitHits. Compact audit JSON and policy verdict JSON are for automation and cannot be used as replay inputs.

Exit codes

Use these distinctions to handle failures in CI. Read the diagnostic before rerunning an online command: it submits a new job and can consume quota again.