Skip to main content
Record the projects you intend to scan and the licenses you allow in githits-scan.toml. Scan uses this file to check for inventory changes before uploading and to enforce your license policy. This repository configuration is separate from the githits CLI configuration.

​
Save a reviewed inventory

Without configuration, Scan selects the lockfiles it discovers and projects that have a manifest without a lockfile. Start by previewing the selection locally:
Review the inventory and the contents of the selected files. Then save the selection:
--save creates a commented configuration template or updates an existing file. It preserves comments, license policy, and exclusions. The example below selects two lockfiles and one project without a lockfile. Replace the paths with your own:
githits-scan.toml
Use forward slashes in paths. Paths stay relative to the scan root even if you keep the configuration elsewhere. Use --config FILE to select another file. Scan rejects unknown keys, unsupported versions, and a missing file supplied with --config. To create a new configuration at a chosen path, run detect --config FILE --save.

​
Inventory drift

When you have a saved configuration, Scan calls new or missing projects inventory drift. Commands return exit 1. Online analysis stops before submitting a request. Run detect to inspect the changes. If the new inventory is intended, run detect --save and review the configuration diff before committing it. To scan the configured selection despite drift, pass --no-check. This does not add newly discovered projects, disable audit findings, or bypass license policy. You cannot combine it with detect --save.

​
Exclusions and discovery

Scan honors Git ignore rules. It skips hidden entries, symbolic links, and installed-dependency directories such as node_modules and vendor. By default, Scan also skips directories named fixtures, __fixtures__, testdata, test-data, or test_data, ignoring ASCII case. Ordinary test, eval, and truth directories remain eligible. Review the inventory for your repository.

​
Exclude package files

Use repeated --exclude options to omit package files:
These patterns also apply to associated manifests and workspace member manifests. A pattern ending in /** skips the matching directory subtree before Scan reads its contents. Unreadable directories that haven’t been excluded stop discovery with exit 3. Selection follows these rules:
  • Explicit configuration entries can select projects from the default fixture exclusions and override configuration exclude patterns. They preserve any parent directories Scan needs to reach those files.
  • Command-line exclusions take precedence over configuration inclusions.
  • detect --save saves command-line exclude patterns. Existing inclusion overrides remain unless a command-line pattern excludes them.

​
Scan projects without lockfiles

Scan includes projects that have a manifest without a lockfile by default. GitHits resolves their declared dependency constraints, so the result can differ from an installed or previously locked build. Use --lockfiles-only to skip unconfigured projects without lockfiles. Scan still includes associated manifests and eligible declared Cargo/npm workspace members. Other nested manifests need explicit configuration. A manifest’s location near a lockfile does not establish that the lockfile covers its dependencies.

​
Supported package files

Scan recognizes exact filenames, including case. Renaming a file does not convert its format. When a lockfile has an associated manifest, Scan includes that manifest if present. Resolution and audit coverage vary by ecosystem. Check the results for incomplete information. Recognizing a file does not guarantee that GitHits can resolve all of its dependencies. For upload limits and result interpretation, see lockfile analysis.

​
License policy

Use license report to read license information without a policy. To enforce a policy, first run detect --save, then enable or edit [licenses] in the generated configuration:
Check the policy online or against a saved CycloneDX JSON document:
Use explicit SPDX identifiers and AND/OR/WITH expressions. Scan does not guess license names or interpret slash-separated license text. Missing or unrecognized licenses, policy violations, and unresolved projects return exit 1. Scan excludes nodes marked as project roots or local sources from the check. It still checks their children. A local path alone does not establish first-party ownership.

​
Package exceptions

Add package exceptions with [[licenses.exceptions]] entries containing a versionless purl and a reason. An exception exempts the entire package from the allow list. Review that scope before adding one. Each applied exception’s reason appears in the report.