Skip to content
jbisfunPublic

About

git multiplexer

Resources

Stars

0 stars

Watchers

0 watching

Forks

Latest commit

 

History

15 Commits

Folders and files

NameName
Last commit message
Last commit date
 
 
 
 
 
 
 
 
 
 
 
 
 
 

Repository files navigation

pull

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.

Crates and features

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.

Files

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.

Commands

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.

Ignore

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.

MCP server

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.

Jobs and sessions (launchd)

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.

About

git multiplexer

Resources

Stars

0 stars

Watchers

0 watching

Forks

Releases

Packages

Contributors

Languages