> ## Documentation Index
> Fetch the complete documentation index at: https://docs.githits.com/llms.txt
> Use this file to discover all available pages before exploring further.

# Configure Scan

> Choose which package files Scan uploads, save a reviewed inventory, and set a license policy in githits-scan.toml.

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](https://docs.githits.com/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:

```bash theme={null}
githits-scan detect
```

Review the inventory and the [contents of the selected files](https://docs.githits.com/scan/overview.md#review-what-you-upload). Then save the selection:

```bash theme={null}
githits-scan detect --save
git add githits-scan.toml
```

`--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:

```toml githits-scan.toml theme={null}
version = 1

[lockfiles]
include = ["Cargo.lock", "web/package-lock.json"]
exclude = ["examples/**"]
manifests = ["services/legacy/package.json"]
```

| Key | Meaning |
| - | - |
| `version` | Configuration schema version; must be `1`. |
| `lockfiles.include` | Exact lockfile paths in the reviewed inventory. |
| `lockfiles.exclude` | Glob patterns for package files to omit. |
| `lockfiles.manifests` | Exact manifest paths to scan, including projects without a lockfile. |
| `licenses` | Optional license policy; required for `license check`. |

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:

```bash theme={null}
githits-scan detect --exclude 'examples/**' --exclude 'test/**'
```

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.

| Ecosystem | Lockfiles | Associated manifest or input without a lockfile |
| - | - | - |
| Rust | `Cargo.lock` | `Cargo.toml` |
| JavaScript (npm, pnpm, Yarn, Bun) | `package-lock.json`, `npm-shrinkwrap.json`, `pnpm-lock.yaml`, `yarn.lock`, text `bun.lock` | `package.json` |
| Python (uv, Poetry, PDM) | `uv.lock`, `poetry.lock`, `pdm.lock` | `pyproject.toml` |
| Python (Pipenv) | `Pipfile.lock` | No paired manifest |
| Swift | `Package.resolved` | `Package.swift` |
| Gradle | `gradle.lockfile`, `buildscript-gradle.lockfile`, `settings-gradle.lockfile`, `gradle/dependency-locks/*.lockfile` | `build.gradle` or `build.gradle.kts` as an input without a lockfile or when explicitly configured |
| .NET / NuGet | `packages.lock.json` | A single `.csproj` in its directory; multiple files make the lockfile ambiguous |
| Dart / Flutter | `pubspec.lock` | `pubspec.yaml` |
| PHP / Composer | `composer.lock` | `composer.json` |
| Elixir / Mix | `mix.lock` | `mix.exs` |
| Ruby / Bundler | `Gemfile.lock`, `gems.locked` | `Gemfile` pairs with `Gemfile.lock`, not `gems.locked` |
| Erlang / Rebar3 | `rebar.lock` | `rebar.config` |
| C/C++ / Conan | `conan.lock` | No paired manifest |
| Go dep (legacy) | `Gopkg.lock` | No paired manifest |
| Go modules | None | `go.mod` |
| C/C++ / vcpkg | None | `vcpkg.json` |
| Zig | None | `build.zig.zon` |

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.

| Unsupported input | Alternative or limitation |
| - | - |
| Python `requirements.txt`, `constraints.txt`, `setup.py`, `setup.cfg` | Use a supported lockfile or `pyproject.toml`. |
| Deno `deno.lock`, Maven `pom.xml` | No native Deno or Maven input support. |
| Binary Bun `bun.lockb` | Use text `bun.lock`. |
| Go `go.sum`, `go.work` | Scan selects `go.mod`; these files are not uploaded. |
| CocoaPods `Podfile.lock`, Nix `flake.lock`, NuGet `packages.config` / `project.assets.json` | Not supported by Scan. |

For upload limits and result interpretation, see [lockfile analysis](https://docs.githits.com/api/lockfile-analysis.md).

## 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:

```toml theme={null}
[licenses]
allow = ["MIT", "Apache-2.0", "Apache-2.0 WITH LLVM-exception", "BSD-3-Clause", "ISC"]
```

Check the policy online or against a saved CycloneDX JSON document:

```bash theme={null}
githits-scan license check
githits-scan license check --sbom bom.cdx.json
```

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.


This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.