Vendor Workflow: This directory keeps reproducible source snapshots for third-party libraries.

README.md

Vendor Workflow

This directory keeps reproducible source snapshots for third-party libraries. Each library snapshot is derived from:

1. an upstream Git URL;
2. an exact upstream commit hash;
3. an ordered local patch series.

The tracked library directories are snapshots, not working repositories. Use _work/ for local Git commits and _cache/ for upstream mirrors.

Data Flow

              set-library-source.sh
                     |
                     v
        +---------------------------+
        | _manifests/<name>.env     |  tracked input
        | NAME, URL, REVISION,      |
        | PATCH_DIR                 |
        +-------------+-------------+
                      |
                      | checkout-library.sh / restore-library.sh
                      v
        +---------------------------+
        | _cache/<name>.git         |  ignored upstream mirror
        +-------------+-------------+
                      |
                      v
        +---------------------------+
        | _work/<name>/             |  ignored editable Git worktree
        +-------------+-------------+
                      |
          commits     | publish-library.sh
                      v
        +---------------------------+
        | _patches/<series>/*.patch |  tracked local patch series
        +-------------+-------------+
                      |
                      | restore-library.sh / publish-library.sh
                      v
        +---------------------------+
        | <name>/                   |  tracked source snapshot
        +---------------------------+

Directory Map

Path	Tracked	Role	Created or overwritten by
_manifests/<name>.env	yes	Source of truth for NAME, URL, REVISION, and PATCH_DIR.	set-library-source.sh
_patches/<series>/	yes	Local commits exported with git format-patch. Empty series are valid.	publish-library.sh overwrites the selected series
<name>/	yes	Materialized source snapshot used by builds. Never edit directly.	restore-library.sh, publish-library.sh
_cache/<name>.git	no	Bare mirror of the upstream repository.	Any command that needs upstream objects
_work/<name>/	no	Editable Git worktree for local patch commits.	checkout-library.sh, restore-library.sh
_tools/*.sh	yes	Maintenance commands.	Edited manually with normal repository changes
_tools/common.sh	yes	Shared implementation sourced by commands. Not an entrypoint.	Edited manually with normal repository changes

Manifest Fields

NAME=<library-name>
URL=https://example.org/upstream.git
REVISION=<40-character-upstream-commit-hash>
PATCH_DIR=_patches/<patch-series-name>

• NAME selects _cache/<name>.git, _work/<name>/, and <name>/.
• URL must be an HTTPS Git URL ending in .git.
• REVISION is the upstream base commit. Local patches are applied on top.
• PATCH_DIR is a relative path under _patches/. It may differ from NAME when one upstream snapshot needs alternate patch series.

Command Matrix

Run commands from vendor/ unless shown otherwise.

Command	Inputs	Overwrites or creates	Does not change
./_tools/set-library-source.sh <name> <url> <revision> [patch-dir]	CLI arguments, upstream Git repository	_cache/<name>.git, _manifests/<name>.env, selected patch directory if missing	<name>/, _work/<name>/, existing patches
./_tools/checkout-library.sh <name>	Manifest, upstream cache, selected patch series	_cache/<name>.git, _work/<name>/	<name>/, _patches/<series>/
./_tools/restore-library.sh <name>	Manifest, upstream cache, selected patch series	_cache/<name>.git, _work/<name>/, <name>/	_patches/<series>/
./_tools/publish-library.sh <name>	Manifest, clean _work/<name>/	_patches/<series>/, <name>/	_manifests/<name>.env, _cache/<name>.git

Important overwrite points:

• checkout-library.sh deletes and recreates _work/<name>/.
• restore-library.sh deletes and recreates both _work/<name>/ and <name>/.
• publish-library.sh deletes and recreates the selected PATCH_DIR, then refreshes <name>/.
• publish-library.sh refuses to run if _work/<name>/ has uncommitted or untracked changes.

Common Workflows

Add A Library Without Local Patches

cd vendor
./_tools/set-library-source.sh <name> <git-url> <40-char-commit-hash>
./_tools/restore-library.sh <name>

This creates the manifest, creates an empty patch directory, and materializes <name>/.

Add A Library With A Named Patch Series

cd vendor
./_tools/set-library-source.sh <name> <git-url> <40-char-commit-hash> _patches/<series>
./_tools/restore-library.sh <name>

Use this when the patch series name intentionally differs from the library name, for example to keep alternate compatibility series.

Edit Or Add Local Patches

cd vendor
./_tools/checkout-library.sh <name>
cd _work/<name>
git add -- <paths>
git commit -m "Describe one local change"
cd ../..
./_tools/publish-library.sh <name>
./_tools/restore-library.sh <name>

Keep one logical local change per commit. The commit subject and body become the patch explanation, so write them as permanent maintenance notes.

Rebuild A Snapshot From Tracked Metadata

cd vendor
./_tools/restore-library.sh <name>

Use this to verify that a tracked snapshot can be reproduced from _manifests/ and _patches/ alone.

Where To Look When Something Is Unclear

Question	Look here
Which upstream repository and commit are used?	_manifests/<name>.env
Which patch series is active?	PATCH_DIR in _manifests/<name>.env
Why does a local change exist?	Patch commit message in _patches/<series>/*.patch
What will be committed to the main repository?	_manifests/, _patches/, and <name>/
What is safe to delete locally?	_cache/ and _work/; scripts can recreate them
Why did git am fail?	The failing patch in _patches/<series>/ and the upstream REVISION
Why did publish-library.sh fail?	git -C _work/<name> status --short; the worktree must be clean
Why does git diff --check mention patch files?	Patch files may contain intentional diff syntax such as + or -- ; check whether the problem is in source content or only in patch metadata

Rules

• Do not edit tracked snapshots in <name>/ directly; edit _work/<name>/ and publish.
• Do not edit generated patch files by hand; rebuild them through publish-library.sh.
• Do not commit _work/, _cache/, build outputs, or nested .git directories.
• Keep patch series ordered from foundational build/runtime changes to narrower model or compatibility changes.
• Keep library-specific rationale in patch commit messages, not in this generic workflow document.

checkout-library.sh

#!/usr/bin/env bash

# Create an editable git worktree for a vendored library and apply local patches.

set -Eeuo pipefail
IFS=$'\n\t'

cd -- "$(dirname -- "${BASH_SOURCE[0]}")"
source ./common.sh

require_command git
require_command realpath

[[ $# -eq 1 ]] || die "usage: $0 <library-name>"

library="$1"
root="$(vendor_root)"
load_manifest "$root" "$library"

ensure_cache_clone "$root" "$NAME" "$URL"
verify_revision_exists "$root" "$NAME" "$REVISION"
reset_worktree "$root" "$NAME" "$REVISION"
apply_patches "$root" "$NAME" "$PATCH_DIR"

info "Ready: $(work_dir "$root" "$NAME")"

common.sh

#!/usr/bin/env bash

# Shared helpers for vendor maintenance scripts.
# This file is sourced by executable scripts and is not intended to be run
# directly. Keep functions conservative: all user-provided values are validated
# before being used as paths or git arguments.

set -Eeuo pipefail
IFS=$'\n\t'

die() {
  printf 'error: %s\n' "$*" >&2
  exit 1
}

info() {
  printf '%s\n' "$*" >&2
}

script_dir() {
  local source
  source="${BASH_SOURCE[0]}"
  cd -- "$(dirname -- "$source")" >/dev/null 2>&1
  pwd -P
}

vendor_root() {
  local tools_dir
  tools_dir="$(script_dir)"
  cd -- "$tools_dir/.." >/dev/null 2>&1
  pwd -P
}

require_command() {
  local command_name
  command_name="$1"
  command -v -- "$command_name" >/dev/null 2>&1 || die "required command not found: $command_name"
}

validate_library_name() {
  local name
  name="$1"
  [[ "$name" =~ ^[A-Za-z0-9._-]+$ ]] || die "invalid library name: $name"
  [[ "$name" != "." && "$name" != ".." ]] || die "invalid library name: $name"
}

manifest_path() {
  local root name
  root="$1"
  name="$2"
  printf '%s/_manifests/%s.env\n' "$root" "$name"
}

load_manifest() {
  local root name manifest line key value
  root="$1"
  name="$2"
  validate_library_name "$name"
  manifest="$(manifest_path "$root" "$name")"
  [[ -f "$manifest" ]] || die "manifest not found: $manifest"

  NAME=
  URL=
  REVISION=
  PATCH_DIR=
  while IFS= read -r line || [[ -n "$line" ]]; do
    [[ -z "$line" || "$line" == '#'* ]] && continue
    [[ "$line" == *=* ]] || die "invalid manifest line in $manifest: $line"
    key="${line%%=*}"
    value="${line#*=}"
    case "$key" in
      NAME) NAME="$value" ;;
      URL) URL="$value" ;;
      REVISION) REVISION="$value" ;;
      PATCH_DIR) PATCH_DIR="$value" ;;
      *) die "unknown manifest key in $manifest: $key" ;;
    esac
  done < "$manifest"

  [[ -n "$NAME" ]] || die "manifest NAME is required"
  [[ -n "$URL" ]] || die "manifest URL is required"
  [[ -n "$REVISION" ]] || die "manifest REVISION is required"
  [[ -n "$PATCH_DIR" ]] || die "manifest PATCH_DIR is required"
  [[ "$NAME" == "$name" ]] || die "manifest NAME mismatch: expected $name, got $NAME"
  validate_git_url "$URL"
  [[ "$REVISION" =~ ^[0-9a-fA-F]{40}$ ]] || die "REVISION must be a 40-character git hash"
  validate_patch_dir "$PATCH_DIR"
}

validate_git_url() {
  local url
  url="$1"
  [[ "$url" == https://* ]] || die "URL must use https: $url"
  [[ "$url" == *.git ]] || die "URL must end with .git: $url"
  [[ "$url" != *[$' \t\r\n']* ]] || die "URL must not contain whitespace"
}

validate_patch_dir() {
  local patch_dir
  patch_dir="$1"
  [[ -n "$patch_dir" ]] || die "PATCH_DIR must not be empty"
  [[ "$patch_dir" != /* ]] || die "PATCH_DIR must be relative: $patch_dir"
  [[ "$patch_dir" == _patches/* ]] || die "PATCH_DIR must be under _patches/: $patch_dir"
  [[ "$patch_dir" != *[$' \t\r\n']* ]] || die "PATCH_DIR must not contain whitespace"
  [[ "$patch_dir" != *'//'* ]] || die "PATCH_DIR must not contain empty path segments: $patch_dir"
  [[ "$patch_dir" != */ ]] || die "PATCH_DIR must not end with a slash: $patch_dir"
  case "$patch_dir" in
    '.'|'..'|'./'*|'../'*|*'/.'|*'/..'|*'/./'*|*'/../'*)
      die "PATCH_DIR must not contain . or .. path segments: $patch_dir"
      ;;
  esac
}

ensure_inside_vendor() {
  local root path resolved
  root="$1"
  path="$2"
  resolved="$(realpath -m -- "$path")"
  case "$resolved" in
    "$root"/*) ;;
    *) die "path escapes vendor root: $path" ;;
  esac
}

ensure_parent_inside_vendor() {
  local root path parent
  root="$1"
  path="$2"
  parent="$(dirname -- "$path")"
  ensure_inside_vendor "$root" "$parent"
}

manifest_dir() {
  local root
  root="$1"
  printf '%s/_manifests\n' "$root"
}

cache_parent_dir() {
  local root
  root="$1"
  printf '%s/_cache\n' "$root"
}

work_parent_dir() {
  local root
  root="$1"
  printf '%s/_work\n' "$root"
}

cache_dir() {
  local root name
  root="$1"
  name="$2"
  printf '%s/_cache/%s.git\n' "$root" "$name"
}

work_dir() {
  local root name
  root="$1"
  name="$2"
  printf '%s/_work/%s\n' "$root" "$name"
}

source_dir() {
  local root name
  root="$1"
  name="$2"
  printf '%s/%s\n' "$root" "$name"
}

patch_dir_abs() {
  local root patch_dir
  root="$1"
  patch_dir="$2"
  validate_patch_dir "$patch_dir"
  printf '%s/%s\n' "$root" "$patch_dir"
}

ensure_cache_clone() {
  local root name url cache
  root="$1"
  name="$2"
  url="$3"
  cache="$(cache_dir "$root" "$name")"
  ensure_inside_vendor "$root" "$cache"
  mkdir -p -- "$(cache_parent_dir "$root")"

  if [[ -d "$cache" ]]; then
    info "Fetching $name"
    git --git-dir="$cache" fetch --prune --tags -- "$url" '+refs/heads/*:refs/heads/*'
  else
    info "Cloning $name into cache"
    git clone --mirror -- "$url" "$cache"
  fi
}

verify_revision_exists() {
  local root name revision cache
  root="$1"
  name="$2"
  revision="$3"
  cache="$(cache_dir "$root" "$name")"
  git --git-dir="$cache" cat-file -e "$revision^{commit}" || die "revision not found in cache: $revision"
}

reset_worktree() {
  local root name revision work work_parent cache
  root="$1"
  name="$2"
  revision="$3"
  cache="$(cache_dir "$root" "$name")"
  work_parent="$(work_parent_dir "$root")"
  mkdir -p -- "$work_parent"
  work="$(work_dir "$root" "$name")"
  ensure_inside_vendor "$root" "$work"
  rm -rf -- "$work"
  git clone --no-checkout -- "$cache" "$work"
  # REVISION is validated as a 40-character hex commit hash. It is a revision
  # argument, not a path, so a path separator would be incorrect here.
  git -C "$work" switch --detach "$revision"
}

apply_patches() {
  local root name patch_dir work patch_abs patch_count
  root="$1"
  name="$2"
  patch_dir="$3"
  validate_patch_dir "$patch_dir"
  work="$(work_dir "$root" "$name")"
  patch_abs="$(patch_dir_abs "$root" "$patch_dir")"
  ensure_inside_vendor "$root" "$patch_abs"
  mkdir -p -- "$patch_abs"
  patch_count=0
  shopt -s nullglob
  for patch in "$patch_abs"/*.patch; do
    patch_count=$((patch_count + 1))
    git -C "$work" am -- "$patch"
  done
  shopt -u nullglob
  info "Applied $patch_count patches for $name"
}

sync_worktree_to_snapshot() {
  local root name work source
  root="$1"
  name="$2"
  work="$(work_dir "$root" "$name")"
  source="$(source_dir "$root" "$name")"
  ensure_inside_vendor "$root" "$source"
  rm -rf -- "$source"
  mkdir -p -- "$source"
  rsync -a --delete \
    --exclude '/.git/' \
    --exclude '/.github/' \
    --exclude '/target/' \
    --exclude '/.idea/' \
    --exclude '/.vscode/' \
    --exclude '*.iml' \
    -- "$work/" "$source/"
}

require_clean_worktree() {
  local work
  work="$1"
  [[ -d "$work/.git" ]] || die "worktree is missing or not a git repository: $work"
  if [[ -n "$(git -C "$work" status --porcelain=v1 --untracked-files=all)" ]]; then
    git -C "$work" status --short >&2
    die "worktree has uncommitted changes: $work"
  fi
}

gitignore.txt

vendor/**/.git/
vendor/**/.github/
vendor/**/target/
vendor/_cache/
vendor/_work/

publish-library.sh

#!/usr/bin/env bash

# Export committed worktree changes as patches and refresh the tracked snapshot.

set -Eeuo pipefail
IFS=$'\n\t'

cd -- "$(dirname -- "${BASH_SOURCE[0]}")"
source ./common.sh

require_command git
require_command realpath
require_command rsync

[[ $# -eq 1 ]] || die "usage: $0 <library-name>"

library="$1"
root="$(vendor_root)"
load_manifest "$root" "$library"

work="$(work_dir "$root" "$NAME")"
patch_abs="$(patch_dir_abs "$root" "$PATCH_DIR")"
ensure_inside_vendor "$root" "$patch_abs"

verify_revision_exists "$root" "$NAME" "$REVISION"
require_clean_worktree "$work"

rm -rf -- "$patch_abs"
mkdir -p -- "$patch_abs"

if git -C "$work" merge-base --is-ancestor "$REVISION" HEAD; then
  # Use zeroed commit ids so re-applying and re-publishing the same patch
  # series does not rewrite files only because git am created new commits.
  git -C "$work" format-patch --zero-commit --no-stat --output-directory "$patch_abs" "$REVISION"..HEAD >/dev/null
else
  die "worktree HEAD is not based on manifest REVISION"
fi

sync_worktree_to_snapshot "$root" "$NAME"
info "Published patches and snapshot for $NAME"

restore-library.sh

#!/usr/bin/env bash

# Recreate the tracked vendor snapshot from upstream revision plus patch series.

set -Eeuo pipefail
IFS=$'\n\t'

cd -- "$(dirname -- "${BASH_SOURCE[0]}")"
source ./common.sh

require_command git
require_command realpath
require_command rsync

[[ $# -eq 1 ]] || die "usage: $0 <library-name>"

library="$1"
root="$(vendor_root)"
load_manifest "$root" "$library"

ensure_cache_clone "$root" "$NAME" "$URL"
verify_revision_exists "$root" "$NAME" "$REVISION"
reset_worktree "$root" "$NAME" "$REVISION"
apply_patches "$root" "$NAME" "$PATCH_DIR"
sync_worktree_to_snapshot "$root" "$NAME"

info "Restored: $(source_dir "$root" "$NAME")"

set-library-source.sh

#!/usr/bin/env bash

# Set or update a library manifest after validating the upstream revision.

set -Eeuo pipefail
IFS=$'\n\t'

cd -- "$(dirname -- "${BASH_SOURCE[0]}")"
source ./common.sh

require_command git
require_command realpath

[[ $# -eq 3 || $# -eq 4 ]] || die "usage: $0 <library-name> <git-url> <revision> [patch-dir]"

library="$1"
url="$2"
revision="$3"
patch_dir="${4:-_patches/$library}"
root="$(vendor_root)"

validate_library_name "$library"
validate_git_url "$url"
[[ "$revision" =~ ^[0-9a-fA-F]{40}$ ]] || die "revision must be a 40-character git hash"
validate_patch_dir "$patch_dir"

ensure_cache_clone "$root" "$library" "$url"
verify_revision_exists "$root" "$library" "$revision"

manifest="$(manifest_path "$root" "$library")"
ensure_parent_inside_vendor "$root" "$manifest"
mkdir -p -- "$(manifest_dir "$root")"
cat > "$manifest" <<EOF
NAME=$library
URL=$url
REVISION=$revision
PATCH_DIR=$patch_dir
EOF

mkdir -p -- "$(patch_dir_abs "$root" "$patch_dir")"
info "Updated manifest: $manifest"