Español · Українська

Projectfile Bridges

pf-bridge is the projection tool of the projectfile: it derives forge identity files, assembles feature and roadmap fragments, and projects the projectfile onto the files a forge and repository expect. Companion binary to pf-cli for the projectfile.org tooling.

Features

• Community files without the copypaste
• Feature and roadmap docs that include your parents
• Every forge mirror tells the same story
• Licensed and citable
• One place for your package metadata
• A readme that keeps up with the project
• Release notes written from your history
• Start in minutes, stay in sync afterwards
• Every tool reads the same lists

See Features for the full list.

What this provides

• Executable pf-bridge — command pf-bridge
• Container image ghcr.io/projectfile-org/bridge:latest
• Container image damianbuho/projectfile-bridge:latest

Installation

Container image

Pull the published container image:

Pull from GHCR — linux/amd64, linux/arm64, linux/riscv64

docker pull ghcr.io/projectfile-org/bridge:latest

Pull from DockerHub — linux/amd64

docker pull damianbuho/projectfile-bridge:latest

Stable releases also publish X.Y.Z, X.Y and X tags — pull the precision you want to pin.

If the registries above are unreachable, pull from the origin instead:

Pull from Kiota — linux/amd64

docker pull kiota.ch/projectfile/bridge:latest

Go toolchain

Install with the Go toolchain:

go install projectfile.org/projectfile/bridge/v4/cmd/pf-bridge@latest

Then run pf-bridge --help.

Prebuilt binary

Download the prebuilt binary for your platform from GitHub Releases:

mkdir -p ~/.local/bin
curl --fail --location --output ~/.local/bin/pf-bridge https://github.com/projectfile-org/bridge/releases/latest/download/pf-bridge-$(uname -s | tr A-Z a-z)-$(uname -m)
chmod +x ~/.local/bin/pf-bridge
~/.local/bin/pf-bridge --help

Published for: linux/amd64, linux/arm64, linux/riscv64, darwin/amd64, darwin/arm64

To uninstall, delete that one file: rm ~/.local/bin/pf-bridge.

Usage

pf-bridge

$ pf-bridge --help
pf-bridge — keep every project file in sync with your projectfile document

A projectfile (projectfile.yaml) is the single source of truth for a project:
identity, people, links, and tool config. pf-bridge copies that data out
into the files each tool already reads — README.md, package.json,
CITATION.cff, forge settings — and reads two-way files back.
Spec: https://projectfile.org/specification/

Usage:
  pf-bridge <bridge> [args]   run one bridge (e.g. readme, npm, forge)
  pf-bridge all [flags]       update every file from the projectfile [rw]
  pf-bridge check [flags]     verify declared files match, write nothing [ro]
  pf-bridge to all            write projectfile out to every file [rw]
  pf-bridge from all          read every two-way file back in [rw]
  pf-bridge --list            list installed bridges
  pf-bridge completion SHELL  print completion script (bash|zsh|fish)

[rw] updates files, [ro] only reads or compares. `check` without names
covers the bridges this project declares; `check <name>…` narrows it,
`check --all` covers every installed bridge instead.

Shared flags (also accepted after a bridge name):
  --check, --dry-run, --force, --create-all, --fail-on-drift, --offline,
  --quiet, --verbose. Each has a PF_BRIDGE_* env equivalent.
  Drift warns by default; --fail-on-drift makes it fatal.

Tools:
  cache                Manage the local SPDX and include cache
  forge                Push projectfile metadata out to the repository forge
  init                 Scaffold a new projectfile document (prefer pf-cli init)
  release-notes        Render release notes from git
  scan                 Run scanners to refresh projectfile metadata from filesystem signals
Package manifests:
  composer   [rw]  composer.json — two-way sync
  npm        [rw]  package.json — two-way sync
  pyproject  [rw]  pyproject.toml — two-way sync
  shard      [rw]  shard.yml — two-way sync
Citation and ownership:
  cff          [rw]  CITATION.cff — two-way sync
  codeowners   [rw]  CODEOWNERS — two-way sync
  funding      [ro]  FUNDING.yml — one-way render
  fundingjson  [ro]  funding.json — one-way render
Documentation:
  ai-policy     [ro]  AI_POLICY.md — one-way render
  coc           [ro]  CODE_OF_CONDUCT.md — one-way render
  contributing  [ro]  CONTRIBUTING.md — one-way render
  dei           [ro]  DEI.md — one-way render
  fragments     [ro]  FEATURES.md, ROADMAP.md, … assembled from docs/<name>.d fragments (one-way render)
  readme        [ro]  README.md — one-way render
  security      [ro]  SECURITY.md — one-way render
  support       [ro]  SUPPORT.md — one-way render
Repository setup:
  browserslist     [ro]  .browserslistrc — one-way render
  gitattributes    [ro]  .gitattributes — one-way render
  ignore           [ro]  .claudeignore, .containerignore, .dockerignore, .fdignore, .gitignore, .npmignore, .textlintignore — one-way render
  license          [ro]  LICENSE + LICENSES/<spdx>.txt (one-way render, always overwrite)
  releaserc        [ro]  .releaserc.yaml — one-way render
  vulnerabilities  [ro]  .grype.yaml, .trivyignore, audit-ci.jsonc, osv-scanner.toml — one-way render
  yamllint         [ro]  .yamllint — one-way render

Help per bridge: pf-bridge <bridge> --help

Examples and every command’s help are in Usage.

Building

Clone the repository with its submodules:

git clone --recurse-submodules https://github.com/projectfile-org/bridge bridge && cd bridge

Build the container image locally:

make container-build

• Makefile reference

Run make with no arguments for the default target; run make help to list every target.

For the local dev loop, make dev-container brings up the dev-container.

Pipeline entry points:

• make analyzed — Run the heavy analysis sweep (mutation testing, benchmarks)
• make audited — Re-scan the pinned dependencies and published artifacts for new vulnerabilities
• make check-outdated — Report every pinned dependency that lags upstream
• make release-is-ready — Run the pseudo-CI pipeline locally — build, test and scan, without publishing

Policies

• How to contribute
• Security policy
• Getting support
• Code of Conduct
• AI and LLM Policy

Links

• Projectfile Specification

License

This project is licensed under MIT — see the LICENSE file for details.