---
title: "Projects and references"
description: "Repos you work on, and repos you keep nearby to read."
---

> Documentation Index
> Fetch the complete documentation index at: https://docs.gitpando.com/llms.txt
> Use this file to discover all available pages before exploring further.

# 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`:

```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

```sh
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`:

```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.

Source: https://docs.gitpando.com/references/index.mdx