pl_vendor

pl_vendor copies Git repositories into another repository as ordinary files and records their exact commits in a deterministic YAML lockfile. It supports optional downstream patches and can verify that checked-in vendor trees still match their locked upstream commits.

Requirements

• Python 3.13 or newer
• Git 2.30 or newer

The package has no Python runtime dependencies.

Every command checks the installed Git version before reading or changing vendored trees.

Configuration

Add a dependency interactively:

pl-vendor add

Or provide its settings as arguments (the path defaults to vendor/NAME and the branch defaults to main):

pl-vendor add example https://github.com/example/example.git vendor/example release

This creates or updates plvendor.toml at the root of the consuming Git repository, fetches the dependency, and records its revision. The resulting manifest looks like:

schema_version = 1

[dependencies.example]
path = "vendor/example"
url = "https://github.com/example/example.git"
branch = "release"

The generated plvendor-lock.yaml records the resolved commit:

lockfileVersion: 1

dependencies:
  example: '0123456789abcdef0123456789abcdef01234567'

Optional patches live at .vendor-patches/<dependency-name>.patch and are applied after copying the upstream tree.

Commands

pl-vendor update
pl-vendor update example
pl-vendor add example https://github.com/example/example.git --branch release
pl-vendor remove example
pl-vendor remove first second
pl-vendor lock
pl-vendor lock --check
pl-vendor lock --upgrade
pl-vendor lock --upgrade-package example
pl-vendor sync
pl-vendor sync example
pl-vendor check
pl-vendor verify

Like uv add and uv remove, pl-vendor add and pl-vendor remove update the manifest, lockfile, and installed files together. Remove accepts one or more dependency names and deletes their complete managed trees, including local or generated content. Removing the final dependency also removes the now-unused manifest and lockfile; downstream patches are retained.

pl-vendor lock fills missing lock entries while preferring existing revisions. Pass --upgrade or --upgrade-package NAME to explicitly advance locked revisions; this does not modify vendored files. pl-vendor update remains a convenience command that advances and syncs one or all dependencies in one step. If the manifest exists but the lockfile does not, update bootstraps a complete lockfile from the manifest instead of requiring a separate lock step. Because the lockfile is generated state, update also replaces it when it has uncommitted changes; uncommitted manifest and vendored-tree changes remain protected.

pl-vendor sync does not update the lockfile: it replaces the selected vendored trees with their exact locked revisions and reapplies downstream patches. As with uv's default exact sync, local or generated files inside those managed trees are removed.

Each command discovers the consuming repository from the current directory. Pass --root PATH after the command to operate on a different repository.

Development

This repository uses uv 0.9 or newer to manage its development environment:

uv sync --dev
make test
make format
make build

The test suite is kept in the top-level tests directory so it is separate from the installable pl_vendor package.

To publish a release, start from a clean working tree and run:

make publish-version VERSION=0.2.0

This runs the test suite and static checks, updates pyproject.toml and uv.lock, builds the distributions, creates a release commit and annotated v0.2.0 tag, and atomically pushes both to origin. The tag starts the PyPI publishing workflow. Use REMOTE=name to publish through a different Git remote. The requested version must be semantically newer than the current package version and all local or remote release tags.