Overview
vg bisect <package> <constraint> pinpoints the commit where a dependency crossed a version line. Where vg why narrates every version change, vg bisect answers one targeted question: when did we cross this line? — for example, when a vulnerable dependency was finally patched past the fixed version, or when a major version was adopted.
Usage
vg bisect <package> <constraint>
<constraint> is a version or a semver range. A bare version means "reached or surpassed" — vg bisect lodash 4.17.21 is the same as vg bisect lodash '>=4.17.21'. Pass an explicit range (^18, >=2 <3) when you need one.
What You See
vg bisect reads your lockfile's history — offline, without checking out any commit — and finds the commit that first reached the constraint, with the version before and after, the author, and the date. If the line was never crossed, it tells you so and shows the latest version in history, so an unadopted fix is obvious. A later flip, such as a downgrade that re-introduced the old version, is listed too.
Gate CI With --assert
vg bisect lodash 4.17.21 --assert
With --assert, the command exits non-zero when the current version does not satisfy the constraint, so a pipeline step can block a merge until the fix is adopted.
Exit codes: 0 when the query resolves, 2 when --assert finds the constraint unsatisfied, 3 when the package has no version history, and 5 for an invalid version or range.
Supported Ecosystems
vg bisect works wherever a resolved lockfile is committed: npm / pnpm / yarn, pip / poetry / pipenv, cargo, composer, bundler, go, pub, hex, NuGet, and Maven/Gradle. For Maven/Gradle it reads a resolved gradle.lockfile, or a pom.xml's pinned direct-dependency versions (BOM/dependencyManagement-managed versions aren't resolved). It needs git history, so run it inside a git repository.
JSON Output
vg bisect lodash 4.17.21 --json
Returns the constraint, the current version, whether it is satisfied now, and every crossing as structured JSON.
Related
- vg why — narrate a dependency's full version history
- vg scan --vulns — detect the vulnerabilities a fix would close
- vg scan — the base drift scan