git-third-party

Compared to git-vendor

brettlangdon/git-vendor is the closest existing tool: a Bash wrapper around git subtree that stores vendoring metadata in squash-merge commit messages and follows a Go-style vendor/<host>/<owner>/<repo> layout. If git subtree already meets your needs and you want a thinner UX on top, it works well.

Where git-third-party differs:

• Declarative config plus lockfile. State lives in third-party.toml and third-party.lock, not in commit messages. update --check becomes a one-line CI gate.
• Path filtering. --subdir, --include, --exclude let you vendor only the files you actually use.
• Submodule inlining. Upstream submodules get recursively materialized; git subtree leaves them as broken pointers.
• Local patches. Saved tree-patches reapply via 3-way merge on every update.
• Bindings. Python and Node bindings share the same Go core. git-vendor is shell-only.

# uv tool is the recommended path:
$ uv tool install git-third-party

# pip works too:
$ pip install --user git-third-party

$ npm install -g git-third-party
$ pnpm add -g git-third-party

$ go build -o ~/.local/bin/git-third-party .

Python bindings

The Python wheel bundles a c-shared library, so install needs no Go compiler. Mutating calls accept dry_run= and commit_msg=; every call accepts repo_path=, defaulting to the current directory.

from git_third_party import init, add, list_, version

print(version())
init()
add(dir="vendor/foo", url="https://github.com/x/y", follow="main")
for e in list_():
    print(e.dir, e.commit)

Errors map to GitThirdPartyError and its subclasses: ConfigError, NetworkError, ConflictError, CheckDirtyError.

Node bindings

ECMAScript Modules (ESM) only, ships TypeScript types, requires Node 18 or newer. Same options shape as the Python API; same error hierarchy. The bridge serializes calls process-wide — for parallel work, use worker_threads.

import { init, add, list, version } from "git-third-party";

console.log(version());
init();
add({ dir: "vendor/foo", url: "https://github.com/x/y", follow: "main" });
for (const e of list()) {
  console.log(e.dir, e.commit);
}

The npm package distributes platform binaries through optionalDependencies, the same pattern esbuild and swc use. Installs grab a prebuilt binary; no compiler needed.

Vendor a directory

$ git third-party add third_party/zlib https://github.com/madler/zlib --follow master
$ git commit -m "Vendor zlib"

Pull updates

# all entries:
$ git third-party update

# one entry:
$ git third-party update third_party/zlib

# dry-run — would anything change?
$ git third-party status

$ git commit -m "Update vendored zlib"

List, rename, remove

$ git third-party list
$ git third-party rename third_party/zlib vendor/zlib
$ git third-party remove vendor/zlib

--follow <branch>

Track the branch tip and re-resolve on every update. Default when neither flag is set (resolved from the remote's HEAD).

--pin <tag-or-sha>

Pin to a tag (resolved once and then cached) or to a commit SHA (used as-is). 40-hex-character strings count as SHAs.

Switch tracking mode with set:

# pin to a tag:
$ git third-party set vendor/zlib --pin v1.3.1
# back to a moving branch tip:
$ git third-party set vendor/zlib --follow master

$ git third-party add vendor/foo https://example.com/foo.git \
    --subdir src \
    --include '*.c' --include '*.h' \
    --exclude 'tests/'

--subdir DIR

Start from a subdirectory of the upstream repo. Other paths are dropped before include/exclude run.

--include PATTERN · repeatable

Keep only matching paths. Default keeps everything.

--exclude PATTERN · repeatable

Drop matching paths. Always wins over --include.

Patterns follow .gitignore rules with documented deviations: no trailing /**, no . or .. segments. See git third-party add --help for the full specification. Upstream submodules inline recursively unless excluded.

third-party.toml · hand-edited

Hand-editable intent. Each [[third_party]] table is one vendored directory. Each add/set/rename/remove rewrites the file, dropping any user comments.

third-party.lock · generated

Records the resolved commit and any saved tree-patch per entry. Sorted by dir for stable diffs. Do not edit by hand.

Example third-party.toml

# git third-party — vendored content config.

[[third_party]]
dir = "third_party/zlib"
url = "https://github.com/madler/zlib"
follow = "master"

[[third_party]]
dir = "vendor/foo"
url = "https://example.com/foo.git"
pin = "v1.3.1"
subdir = "src"
include = ["*.c", "*.h"]
exclude = ["tests/"]

Corresponding third-party.lock

# git third-party lockfile — generated; do not edit by hand.
version = 1

[[third_party]]
dir = "third_party/zlib"
commit = "abc1234567890abcdef1234567890abcdef12345"

[[third_party]]
dir = "vendor/foo"
commit = "def4567890abcdef1234567890abcdef12345678"

Common flags

-v / -vv / -q · logging

Debug, trace, or warn-only output. --log-level=trace|debug|info|warn|error sets the level explicitly.

--log-format=text|json

Switch the stderr handler to JSON for machine-readable logs.

--color=auto|always|never

Honors NO_COLOR.

--dry-run

Plan without staging.

-f / --allow-dir-exists

Let add and rename write into a non-empty target.

--profile PATH

Write a CPU profile.

--json

Emit a structured entryResult (or array) on stdout instead of human text. Schema lives in output.go.

--commit MSG

Run git commit -m MSG after the command stages changes.

--check · update / status

Exit non-zero if any entry would change. Useful in CI and pre-commit hooks.

1. Built-in defaults.
2. Per-user: git config --global third-party.<key>.
3. Per-repo: a [settings] table in third-party.toml.
4. Environment variables.
5. CLI flags.

Environment variables

GIT_THIRD_PARTY_LOG_LEVEL

Same as --log-level: trace, debug, info, warn, error.

GIT_THIRD_PARTY_LOG_FORMAT

Same as --log-format: text or json.

GIT_THIRD_PARTY_COLOR

Same as --color: auto, always, never.

GIT_THIRD_PARTY_EXPERIMENTAL

Comma-separated feature names; same as --experimental.

NO_COLOR · cross-tool

Standard convention; disables ANSI color even when --color=auto.

If you need to modify vendored code — a typo fix, a small portability tweak — record it as a tree-level patch. update re-applies the patch via 3-way merge. Conflicts get tagged with a -conflicts suffix in the lockfile, keeping conflicts visible until resolved.

# enable the experimental feature once
$ git config --global third-party.experimental patch

# record local edits as a tree-patch
$ git third-party patch save vendor/foo

# inspect the saved patch via git diff
$ git third-party patch diff vendor/foo

If update produces conflicts, git-third-party stores the patch with a -conflicts suffix; resolve with git add followed by another patch save. Review the resulting commits carefully — the feature is experimental for a reason.