SPAS: Secure Private Asset Sync

Every project relies on files that don't belong in the public or shared Git repository: local .env secrets, developer overrides, test fixtures, API mocks, and internal team notes.

Moving these files elsewhere breaks build paths. Copying them manually across machines is slow and error-prone. Committing them risks secret leaks and repo bloat.

SPAS solves this by bridging the gap:

• Zero Path Rewiring: Your files remain in their expected workspace locations. Build scripts, tests, and IDEs work without modification.
• Clean Main History: Files are automatically ignored in the main project via .git/info/exclude, leaving your .gitignore untouched.
• Dedicated Version Control: Managed assets are versioned, committed, and synced to a dedicated, separate GitHub repository.
• Built-in Safety: Advisory file locking, atomic writes, dry-run previews, and fail-safe recovery protect your workspace from data loss.

┌─────────────────────────────────────────────────────────────────┐
│                        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)

SPAS coordinates three distinct layers:

1. Workspace Layer: Assets live directly at their standard project paths. SPAS manages an owned block in .git/info/exclude so the main repository leaves them untracked.
2. Coordination & Safety Layer: SPAS acquires an OS-level advisory lock and stages updates via atomic same-filesystem renames (/.spas-tmp/).
3. Dedicated Asset Storage: Assets are committed, merged, and pushed to a separate GitHub repository with independent history.

Download the pre-compiled binary for your system from the latest GitHub release, extract it, and place spas (or spas.exe) in your system PATH.

SPAS requires Git 2.43.1 or newer at runtime.

For complete verification and shell completion setup, see the Installation Guide.

go install -trimpath github.com/getspas/spas@latest

Create an empty repository on GitHub (e.g., your-org/project-assets).

Open a terminal in your project workspace and run:

# Link your workspace to the asset repository
spas link your-org/project-assets --transport ssh --branch main

# Add the private assets you want SPAS to manage
spas add config/dev.json testdata/mock-api.json docs/team-notes.md

# Synchronize assets to the linked repository
spas sync

1. spas link — Connects your project workspace to the dedicated asset repository (offline).
2. spas add — Tracks chosen files and creates local exclusion rules in .git/info/exclude (offline).
3. spas sync — Validates, commits, merges, and synchronizes assets with GitHub.

Want to inspect what will happen before modifying files or committing?

spas sync --dry-run
spas diff --stat

SPAS is fully scriptable. Pass --json and explicit policies to run in automated pipelines without interactive prompts:

spas sync --json \
  --message "Update CI environment assets" \
  --conflict abort \
  --existing-exclude preserve \
  --merge-protection skip

For complete details on all flags, exit codes, and policies, consult the Command Reference.

• 📖 Documentation Wiki
• 🚀 Quick Start Guide
• ⚙️ Command Reference
• 🛡️ Safety & Limitations
• 💬 Discussions & Support
• 🐛 Report a Bug
• 🔒 Security Vulnerability Report