Skip to content

Home

Jump to bottom
github-actions[bot] edited this page Oct 18, 2026 · 2 revisions

SPAS Documentation

SPAS keeps private and environment-specific assets in your local project workspace and synchronizes them with a separate GitHub repository. The managed assets remain untracked in your main project repository.

Getting Started

  1. Installation — Download prebuilt binaries, verify checksums, or compile from source.
  2. Quick Start Guide — Connect your workspace, select private files, and run your first synchronization.
  3. Command Reference — Complete syntax, flags, automation recipes, and exit code reference for all CLI commands.
  4. JSON Output Schema — Structured payload contracts and schema versioning for CI/CD automation.
  5. Troubleshooting Guide — Diagnose errors with spas doctor, resolve merge conflicts, and sanitize debug logs.
  6. Safety & Limitations — Review security models, worktree constraints, and supported file types.

Documentation Index

Guide Description
Installation Installation instructions for Linux, macOS, and Windows with SHA-256 verification and shell completion setup.
Quick Start Step-by-step walkthrough linking a workspace, managing assets, and syncing across developer machines.
Command Reference Detailed documentation of all commands (link, add, remove, sync, status, diff, doctor, unlink).
JSON Output Schema Machine-readable JSON output schemas, error envelopes, and automation payloads.
Schema Contracts Independent persisted-state and CLI JSON versions, compatibility policy, and recovery field reference.
Troubleshooting Practical solutions for common errors, conflict resolution procedures, and recovery flows.
Safety & Limitations Security boundaries, filesystem concurrency models, supported file modes, and resource limits.

Core Concepts & Architecture

SPAS separates project files from managed assets while keeping both in the workspace:

┌─────────────────────────────────────────────────────────────────┐
│                        Project Workspace                        │
│                                                                 │
│   ┌────────────────────────┐      ┌─────────────────────────┐   │
│   │     Tracked Files      │      │     Managed Assets      │   │
│   │    (Main Git Repo)     │      │     (SPAS Managed)      │   │
│   └───────────▲────────────┘      └────────────▲────────────┘   │
│               │                                │                │
│               │     Excluded from Main Repo    │                │
│               │   ◄─────────────────────────   │                │
│               │      (.git/info/exclude)       │                │
└───────────────┼────────────────────────────────┼────────────────┘
                │                                │
         Normal Git Ops                      SPAS Sync
      (git push / git pull)            (spas sync / checkout)
                │                                │
                ▼                                ▼
        Main Git Remote              Linked GitHub Repository
     (Public or Shared Repo)        (Dedicated Asset Storage)
  • Project Repository: Your primary Git repository containing application source code. Managed assets are kept untracked here via local exclusion rules.
  • Project Workspace: The active working tree of your project repository where your code, build scripts, and managed assets live.
  • Linked Repository: The dedicated GitHub repository (public or private) that stores and versions your managed assets.
  • Managed Asset: Any regular file enrolled with spas add whose contents and version history are synced to the linked repository.
  • Managed Checkout: The isolated local clone maintained by SPAS in your user data directory to stage, commit, and merge assets safely before writing them to the workspace.

Supported Boundary

SPAS requires:

  • Runtime Requirement: Git 2.43.1 or newer.
  • Worktree Model: One project worktree per Git common directory.
  • Branching: One linked repository and fixed branch per project workspace.
  • File Modes: Standard regular files (100644 standard and 100755 executable).

Note

SPAS deliberately rejects symlinks, directory junctions, Git submodules, Git LFS pointers, and directory ownership wildcards to ensure deterministic cross-platform synchronization. For complete details, see Safety and Limitations.

Community & Support

SPAS Repository · Releases · Discussions & Q&A

Documentation

Development

Community & Support

Clone this wiki locally