sheet-git

sheet-git is the workspace-scoped Spreadsheet Git control plane for agent-sheet workspaces.

Phase 1 is local-first and commit-history-first:

• local entries only
• one workspace = one repo
• one commit can include multiple workbooks
• one workbook contributes at most one changeset to a commit
• repo truth lives under .sheet-git/
• capture still requires durable local substrate, but stage now auto-flushes dirty local mutations before capture when it can

Current Commands

sheet-git init
sheet-git stage --entry-id <id> [--entry-id <id>...]
sheet-git stage --all
sheet-git reset --entry-id <id> [--entry-id <id>...]
sheet-git reset --all
sheet-git status
sheet-git commit --message "..."
sheet-git checkpoint list
sheet-git checkpoint create <name> [<commit>]
sheet-git history [--limit <n>]
sheet-git show [<commit-or-checkpoint>]
sheet-git diff
sheet-git diff <commit-or-checkpoint>
sheet-git diff <base> <target>
sheet-git blame --entry-id <id> --cell <Sheet!A1> [<commit-or-checkpoint>]
sheet-git fetch origin <entry-id>
sheet-git pull origin <proposal-or-entry-id>
sheet-git pull origin --force-to-latest <proposal-or-entry-id>
sheet-git rebase origin <entry-id>

Supported revision selectors:

• HEAD
• full commit id
• unique commit id prefix
• checkpoint:<name>

Phase 1 Workflow

1. Use agent-sheet to edit a local workbook entry.
2. Run sheet-git stage --entry-id <id> or sheet-git stage --all. stage auto-flushes dirty local mutations before capture when it can.
3. Inspect staged state with sheet-git status or sheet-git diff. status distinguishes staged, unstaged local, and blocked local changes.
4. Commit with sheet-git commit --message "...".
5. Inspect history with sheet-git history / sheet-git show.
6. Create a stable named pointer with sheet-git checkpoint create <name>.
7. Trace a cell with sheet-git blame --entry-id <id> --cell <Sheet!A1>.

For origin-facing collaboration:

1. Use sheet-git fetch origin <entry-id> to inspect remote confirmed revision and pull readiness.
2. Use sheet-git pull origin <entry-id> only when readiness is ready.
3. Use sheet-git pull origin --force-to-latest <entry-id> only for local materialization repair.
4. If fetch origin reports rebase-required, use sheet-git rebase origin <entry-id> to replay the local-only linear continuation on top of the newer confirmed remote base.

Workspace Layout

.agent-sheet/
  entries/
    ei_xxxxxxxx/
      runner/
        workbook.snapshot.json
        workbook.mutations.jsonl

.sheet-git/
  HEAD
  index.json
  meta.json
  refs/
    heads/
      main
    checkpoints/
  objects/
    snapshots/
    commits/
    artifacts/
  transactions/
    commit.json
  locks/
    write.lock
  logs/
    events.jsonl

Boundaries

• agent-sheet owns editing, entry metadata, and runner integration.
• sheet-git owns staged state, commit history, checkpoints, and blame.
• sheet-git reads persisted local-entry files only. It does not read live in-memory runner state.
• first-commit summaries include initial payload signal for added sheets instead of looking empty by default
• blame in Phase 1 is cell-level only. Structural blame is intentionally deferred.