Metadata-Version: 2.4
Name: pl_vendor
Version: 0.2.0
Summary: Vendor Git repositories as ordinary files with a reproducible lockfile
Requires-Python: >=3.13
Description-Content-Type: text/markdown

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

```sh
pl-vendor add
```

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

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

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

```toml
schema_version = 1

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

The generated `vendor-lock.yaml` records the resolved commit:

```yaml
lockfileVersion: 1

dependencies:
  example: '0123456789abcdef0123456789abcdef01234567'
```

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

## Commands

```sh
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.

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

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

```sh
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.
