git-pkgs — dependency history & supply-chain analysis for git repos

What it is

git-pkgs (Go rewrite of a Ruby tool) indexes your repository's dependency history into a SQLite database at .git/pkgs.sqlite3 and exposes it as git pkgs <cmd>. The summary lists its security surface; what it omits is the operational shape that decides whether this fits your setup — the offline/network split, the CI persistence knobs, and a hard limitation on private registries.

Setup and the offline/network boundary

Setup is a one-time git pkgs init, which also installs git hooks so the database updates automatically on commit (--no-hooks to skip; manage later with git pkgs hooks). After upgrading the binary you may need git pkgs upgrade to rebuild on schema changes.

The core commands (list, history, blame, diff, stale, stats, where, log) run entirely from git history with no network access. A distinct set fetches external data: vulns hits OSV; outdated, freshness, licenses, funding, maintainers, health, deprecated, provenance, and changelog query ecosyste.ms. Registry metadata is cached 24h. This matters for choosing what to run in restricted CI.

Preconditions

• Commit your lockfiles. Manifests only show version ranges; lockfiles show resolved and transitive versions. History quality depends on this.
• Network commands depend on ecosyste.ms availability. For airgapped/private setups, git config pkgs.direct true (or GIT_PKGS_DIRECT=1) queries registries directly.

What to do

Persist the DB across CI runs (it lives in .git by default) with an env var:

GIT_PKGS_DB=/path/to/cache.sqlite3

Register with the polite pool for ecosyste.ms to avoid the shared anonymous pool: GIT_PKGS_ECOSYSTEMS_FROM=<email> (or GIT_PKGS_ECOSYSTEMS_API_KEY).

Dependency-aware bisect to find when a capability was introduced — not just a version bump:

git pkgs bisect start HEAD v1.0.0
git pkgs bisect run sh -c 'capslock | grep -q NETWORK && exit 1 || exit 0'

Same pattern finds when a disallowed license entered:

git pkgs bisect run sh -c 'git pkgs licenses --allow=MIT,Apache-2.0 >/dev/null 2>&1'

Semantic lockfile diffs in normal git diff output: git pkgs diff-driver --install.

Caveats

• Private/authenticated registries are not fully supported. git-pkgs extracts registry URLs from lockfile resolved/source/dist.url/remote: fields, but it does not read .npmrc or .pypirc, and authenticated private registries "aren't supported yet for registry queries." If your dependencies live behind auth, the network commands will not resolve them.
• health scores are heuristic (start at 100, deducted for single/small maintainer teams, low usage, missing data); the page notes single-maintainer packages "are not inherently unsafe."
• provenance reports npm attestations separately because their metadata doesn't identify OIDC publishing, and registry signatures count only as a weaker signal.
• Submodules are skipped by default; use --include-submodules.