A multi-repo git wrapper. pullfile.plist lists the repos, their upstreams and pinned
commits. Each repo is cloned to {pullfile-root}/{repo-name}. A single pull commit writes
one commit, with the same message, identity and signature, to every repo that has changes,
then records the new pins.
pull is a cargo workspace. The core is always built; everything else is an optional
crate behind a cargo feature of the pull binary, and no feature requires another:
crate feature what
pull-core (always) pullfile.plist / local.toml model, identity, path routing
pull-git (always) clone/sync, status, stage, commit across repos, push
https, ssh git transports (git2 features)
pull-env env pullfile `env` + local.toml `[env]`; pull env / pull shell
pull-hooks hooks pullfile `hooks` (precommit, postcommit, pull)
pull-lint lint pullfile `lint`; pull lint
conventional lint `conventional` (Conventional Commits parser)
pull-ignore ignore pullfile `ignore` -> each repo's .git/info/exclude
pull-worktree worktree pull worktree
pull-launchd launchd pullfile `jobs`; pull launchctl / pull session
pull-mcp mcp pull mcp (session/job tools only with `launchd`)
All features are on by default. Build a smaller pull with e.g.
cargo install --path . --no-default-features --features https,env,hooks
Features meet only in the binary (src/workspace.rs): without env, hooks, jobs, each
and MCP exec get just PULL_ROOT; without hooks or lint, commits skip them; without
launchd, the MCP server has no session tools. Only identity and repos are core
pullfile keys: every other top-level key is a section owned by its feature crate, kept
verbatim (and reported as ignored) when that feature isn't built, so a lean build never
drops another build's settings. pull --version and pull status --json (features)
list what a binary was built with.
pullfile.plist (shared, committed):
identity: org (selects [orgs.<org>] in local.toml), email = none|local, require_signing
repos: [{name, upstream, branch, commit}]
env: path, vars (feature env)
lint: no_description, max_subject_length, conventional, no_trailing_period
(feature lint)
hooks: precommit, postcommit, pull (feature hooks; arrays of `sh -c` commands,
run in the root)
ignore: [patterns] (feature ignore)
jobs: [launchd jobs] (feature launchd)
Hook env: PULL_ROOT, PULL_HOOK, PULL_REPOS (space-separated), PULL_MESSAGE (commit hooks).
local.toml (per machine, gitignored; falls back to ~/.config/pull/local.toml):
name = "jp"
# email = "..." # only used if the pullfile says email = "local"
signing_key = "FPR" # gpg key; omit to use gpg's default key
sign = true
# gpg_program = "gpg"
[orgs.acme] # overrides used when the pullfile sets org = "acme"
name = "jp@acme"
signing_key = "FPR"
With the default email = none, commits are written as name <>, so no email gets published.
pull init [--org X] create pullfile.plist and local.toml
pull repo add URL [--name] [--branch] | repo rm NAME | repo list
pull sync clone missing repos, fetch, fast-forward to the pins
pull update fast-forward to upstream branches and re-pin
pull status [--json] --json: root, features, lint rules, per-repo
branch/head/pin, ahead/behind and changed files
pull add PATHS... each path is staged in the repo that contains it
pull unstage PATHS... back to HEAD, routed the same way
pull commit -m MSG [-a] [PATHS...] [--no-verify]
pull push
pull lint MSG | pull whoami | pull each CMD...
If the root is itself a git repo, pull commit also commits the updated pullfile.plist
there with the same message.
The pullfile's ignore array holds gitignore patterns for every repo, e.g.
__pycache__/, *.pyc, .DS_Store. pull keeps them in each repo's .git/info/exclude
(between # >>> pull ignore markers) on every command, so repos don't need their own
.gitignore entries and nothing is committed for it. Patterns don't untrack files that are
already committed; git rm --cached those.
pull mcp [--root DIR] serves the workspace to agents over MCP (stdio):
workspace repos, branches, pins, ahead/behind, changes, env, jobs
status / diff / log per repo or across all repos
grep / list_files / read_file ripgrep's engine, .gitignore-aware, confined to the root
exec run a command to completion with the workspace env
session_new / session_run / session_send / session_capture / session_list /
session_kill stateful terminals (the sessions below); a human can
`pull session attach` to the same one
job start/stop/restart/unload pullfile jobs
Register it with an agent, e.g. Hermes:
hermes mcp add pull --command pull --args mcp --root /path/to/workspace
pull mcp-servers prints pull itself plus every pullfile mcp_servers entry as JSON
({name: {command, args, env}}, command resolved on $PATH, PULL_ROOT set), for an
editor/agent to register the whole set at once. A pullfile entry needs only a command
(defaults to the key) and args:
<key>mcp_servers</key>
<dict>
<key>radar</key>
<dict><key>args</key><array><string>mcp</string></array></dict>
</dict>
ycode-pull reads pull mcp-servers to register all of them in one go.
pull ports launchd's job model (Apple's launchd, liblaunch/launch.h) to the workspace.
Jobs use launchd plist keys, either in the pullfile's jobs array or in standalone
.plist files:
Label, Program, ProgramArguments, EnvironmentVariables, WorkingDirectory, RunAtLoad,
KeepAlive (bool or {SuccessfulExit}), StartInterval, ThrottleInterval,
StandardOutPath, Disabled, LaunchOnlyOnce
A per-workspace daemon (pull launchd, started automatically, socket .pull/launchd.sock)
supervises them. Every job runs in a pseudo-terminal with the workspace env (pull env)
plus its own EnvironmentVariables and PULL_JOB, so every job is also a session.
pull launchctl load [FILE.plist...] load pullfile jobs, or launchd plists
pull launchctl list | print LABEL (--json for agents)
pull launchctl start|stop|unload LABEL
pull launchctl kickstart [-k] LABEL start, or kill and restart
pull launchctl shutdown stop all jobs and the daemon
tmux-style sessions, for humans and agents:
pull session new NAME [-d] [-c DIR] [--keep-alive] [CMD...] default CMD: $SHELL
pull session attach NAME detach with ctrl-\
pull session ls [--json] running program + its directory per session
pull session send NAME [-e] TEXT type into it (-e: press enter)
pull session capture NAME [-e] print its screen (-e: keep colours)
pull session run NAME CMD... agents: type CMD, wait for output to settle,
print the screen
pull session kill NAME
StandardErrorPath is accepted, but a terminal merges stderr into stdout, so both go to StandardOutPath.