Projects and references

Some git repos in your repository are yours to work on. Others are someone else’s code you keep nearby to read: a library’s source, an example, a docs repo. Pando tells them apart by where they sit, and treats each the right way.

acme/
  research/infra/workers-oauth-provider/   a reference: read it, never edit it
  projects/web/                            a project: worked on, reviewed, merged

The rule

Pando looks for every folder that has its own .git.

• Under projects/, it is a project. You and your agents work on it: branches, worktrees, review, and a protected main. Pushes go to Pando.
• Anywhere else, it is a reference. Pando never syncs its files and never takes pushes for it.

pando init sorts them this way when it makes the repository, and lists both before it changes anything.

What a reference does on other machines

The repository’s shared files carry a small pointer for each reference: the repo’s address, the branch it follows, and the exact commit you have. It lives at .pando/references/<path>.toml:

url = "https://github.com/cloudflare/workers-oauth-provider.git"
ref = "refs/heads/main"
commit = "0123456789abcdef0123456789abcdef01234567"

On another machine, pando reference sync clones the folder read-only at that commit, fetched straight from the original repo. A reference is cloned only when you ask, since a clone downloads every file: pando clone says how many references it left out, and pando status lists each one as not here until it is cloned. In an agent’s sandbox that Pando runs, where worktrees are mounted, pando clone mounts every reference at once. So the code you keep for reference follows you, and your agents, everywhere.

The machine that has the real repo keeps it as it is.

Keep it current

pando reference update research/infra/workers-oauth-provider

That moves the pointer to the newest commit of the branch it follows. Every machine running pando sync receives the new pointer and moves its folder to that commit, if it has the folder. pando reference sync makes this machine’s reference folders match every pointer: it clones the missing ones and moves the ones behind.

Exceptions

If a repo outside projects/ should be a project, or one inside should be a reference, add one line to .pando/pando.toml:

projects = ["tools/release-scripts"]
references = ["projects/vendored-sdk"]

Private references

A reference that needs a login uses the git access each machine already has. A machine without access makes the folder with one file, PANDO-UNAVAILABLE.txt, that says which address failed and why, instead of leaving it empty.

A reference’s address never carries a password or token: pando init removes one before it writes the pointer.