8000 GitHub - weslien/ws: Workspace graphs for Git — mutable workspaces from immutable, content-addressed layers. Branch from uncommitted state without Git index races. 10 multi-agent scenarios. · GitHub
[go: up one dir, main page]

Skip to content
8000
weslienPublic

About

Workspace graphs for Git — mutable workspaces from immutable, content-addressed layers. Branch from uncommitted state without Git index races. 10 multi-agent scenarios.

Resources

Stars

2 stars

Watchers

0 watching

Forks

Repository files navigation

ws — Workspace Graphs for Git

ws

Fast, lightweight workspace graphs for Git repositories.

ws creates mutable workspaces from immutable layers — think lightweight branching for entire working directories. Branch from another agent's workspace. Isolate to a clean base. Diff, commit, and garbage-collect — all without touching Git itself.

On Linux, workspaces are overlayfs mounts (instant fork, zero-copy). On macOS, they use efficient directory copies — or, when Apple Container is installed, lightweight Linux VMs (auto-detected, no configuration needed). The CLI and graph model are identical on every platform.

# Start from a repository
$ ws get base:https://github.com/you/project --name=feature-a
workspace feature-a formed from a3f4d...

# Work inside it
$ ws run feature-a -- npm install

# Branch — build on another agent's work
$ ws get ws:feature-a --name=feature-b
workspace feature-b formed from 8c2e1...

# Diff against the base
$ ws diff feature-a
--- a/package.json
+++ b/package.json
@@ -1,3 +1,5 @@
 {
-  "version": "1.0.0"
+  "version": "1.1.0"
   "dependencies": {
     "express": "^4.21.0"
+    "lodash": "^4.17.21"

# Promote changes to a permanent layer
$ ws keep feature-a --message="added lodash"
kept layer 8c2e1ba7d3f4...

# See the graph
$ ws graph feature-b
ws:feature-b [active]
  └─ layer:8c2e1ba7d3f4 [added lodash]
    └─ layer:a3f4d9c2e1b5 [base:https://github.com/you/project#HEAD]

Install

Linux / macOS

curl -sSL https://raw.githubusercontent.com/weslien/ws/main/install.sh | bash

The installer tries, in order:

  1. Prebuilt binary from the latest GitHub release — checksum-verified against the published .sha256 asset
  2. Source build at the release tag (needs git + go 1.23+) — version injected via ldflags
  3. go install as a last resort

Overrides: VERSION=vX.Y.Z installs a specific release; INSTALL_DIR=/path changes the install location. Default location is /usr/local/bin if writable, otherwise ~/.local/bin — make sure it's in your PATH:

export PATH="$HOME/.local/bin:$PATH"  # if installed to ~/.local/bin

Optional: manual install with go-task

git clone https://github.com/weslien/ws.git
cd ws
go install github.com/go-task/task/v3/cmd/task@latest
task install   # builds with version injection and installs to ~/.local/bin

Or without go-task:

git clone https://github.com/weslien/ws.git
cd ws
go build -ldflags "-s -w -X main.version=v0.5.2" -o ws ./cmd/ws

Development

git clone https://github.com/weslien/ws.git
cd ws
go install github.com/go-task/task/v3/cmd/task@latest

task build          # build binary
task test           # unit tests
task e2e            # end-to-end lifecycle test (30 checks)
task check          # lint + test + e2e
task --list         # see all tasks

Windows

Prebuilt binaries are provided for Windows amd64 and arm64 in each GitHub Release. Download the .tar.gz for your architecture, extract, and add the directory to your PATH.

Building from source also works:

git clone https://github.com/weslien/ws.git
cd ws
go build -o ws.exe ./cmd/ws

Verify

ws graph
# → Layers:
# → Workspaces:

macOS: Linux VM workspaces via Apple Container

On macOS, ws uses efficient directory copies by default. For per-workspace Linux VMs (real Linux kernel; execution and file operations happen inside the VM while the workspace stays visible on your Mac), install Apple Container:

brew install container
container system start   # first run prompts to install a Linux kernel

Requirements: macOS 26 (Tahoe) or later, Apple Silicon (M1+).

With the CLI installed, ws auto-detects it and routes each new workspace through a container machine — same graph model, same commands. No configuration needed.

WS_BACKEND=copy ws ...        # force directory copies (e.g. inside VMs-in-VMs)
WS_BACKEND=container ws ...   # require the container backend (errors if not installed)

Notes:

  • Prefer hyphens in workspace names — container machine identifiers do not allow underscores (ws sanitizes them, but distinct names can collide: bug_1 and bug-1 both map to machine ws-bug-1).
  • First fork per machine boots a VM and stages the layer content into it; subsequent ws keep/ws diff run inside the VM while the workspace directory stays visible (and directly usable) on your Mac.
  • In-VM overlayfs is planned but deliberately not enabled yet: ws run executes on the Mac, and a VM-side overlay would hide host writes from ws keep. See issue #1.

Concepts

Term Definition
Layer An immutable, content-addressed directory. Stored in ~/.ws/layers/<hash>. Once created, never changes. The unit of sharing.
Workspace A mutable working directory. Stored in ~/.ws/workspaces/<name>. Created from a layer (formed_from). You keep it to promote to a new layer, or drop it to destroy.
Graph The provenance chain of a workspace: the sequence of parent → parent → base layers. ws graph prints this tree.

How it differs from Git worktrees

Git worktrees let you check out multiple branches into separate directories. ws is different:

  • Branch from uncommitted work — ws get ws:agent-a captures agent-a's current dirty state, not just a committed branch.
  • Isolation is explicit — ws get layer:base gives a clean slate from the immutable base, not whatever happens to be on main right now.
  • No Git indexing — operations don't touch .git/index, so there's no risk of index corruption from concurrent agent access.
  • Content-addressed base layers — a layer with hash a3f4d... is exactly that content, forever. No ambiguity about what "HEAD" meant at fork time.

Source types

Source Meaning
layer:<hash> Fork from an immutable layer
ws:<name> Branch from another workspace's current state (snapshot-first)
base:<repo>#<ref> Clone a git repo, create a layer from it, fork from that layer
dir:<path> Create a workspace from a local directory (no git repo needed)

Commands

Command Description
ws get <source> --name=<ws> Create a workspace from a layer, another workspace, or a git repo
ws run <ws> -- <cmd...> Execute a command inside a workspace's filesystem
ws diff <ws> [target] Diff workspace vs its base, or vs another workspace/layer
ws keep <ws> [--message=...] Materialize workspace changes as an immutable layer
ws drop <ws> Destroy workspace and all uncommitted changes
ws graph [ws] Print the layer + workspace DAG, or a specific workspace's provenance
ws layer ls List all layers
ws layer show <hash> Show layer metadata
ws layer gc Garbage-collect unreferenced layers

ws get — Create a workspace

# From a layer
ws get layer:a3f4d9c2e1b5 --name=feature-a

# From another workspace (snapshot first, branch second)
ws get ws:feature-a --name=feature-b

# From a git repo
ws get base:https://github.com/you/project#main --name=feature-c
ws get base:/path/to/local/repo --name=feature-d

ws run — Execute inside a workspace

ws run feature-a -- cat package.json
ws run feature-a -- npm install
ws run feature-a -- go test ./...

On Linux, the workspace is a mounted overlayfs — all writes go to the private upper directory.

ws diff — Compare changes

# Diff workspace vs the layer it was forked from
ws diff feature-a

# Diff two workspaces
ws diff feature-a feature-b

# Diff workspace vs a specific layer
ws diff feature-a layer:a3f4d9c2e1b5

ws keep — Promote to layer

ws keep feature-a --message="installed dependencies"
# → kept layer 8c2e1ba7d3f4

After keep, the new layer is recorded in the graph. The workspace now tracks from the new layer as its base.

ws drop — Destroy

ws drop feature-a

All uncommitted changes are lost. The workspace directory is removed.

ws graph — Visualize

# All layers and workspaces
ws graph

# Provenance tree for a specific workspace
ws graph feature-b

ws layer — Layer management

ws layer ls
ws layer show a3f4d9c2e1b5
ws layer gc        # removes layers no longer referenced by any workspace

Worked Example

# 1. Create a test repository
mkdir /tmp/demo && cd /tmp/demo
git init
echo '{"name": "demo"}' > package.json
git add . && git commit -m "initial"

# 2. Form a workspace
ws get base:/tmp/demo --name=agent-1
# → created layer a3f4d9c2e1b5...
# → workspace agent-1 formed from a3f4d9c2e1b5

# 3. Modify
ws run agent-1 -- sh -c 'echo {"version": "1.0"} > package.json'
ws diff agent-1
# → --- package.json
# → +++ package.json
# → @@ -1 +1 @@
# → -{"name": "demo"}
# → +{"version": "1.0"}

# 4. Branch — agent-2 sees agent-1's work
ws get ws:agent-1 --name=agent-2
ws run agent-2 -- cat package.json
# → {"version": "1.0"}

# 5. Isolate — agent-3 gets the clean base
ws get layer:a3f4d9c2e1b5 --name=agent-3
ws run agent-3 -- cat package.json
# → {"name": "demo"}

# 6. Commit agent-1's changes
ws keep agent-1 --message="added version"
# → kept layer 8c2e1ba7d3f4...

# 7. See the graph
ws graph agent-2
# ws:agent-2 [active]
#   └─ layer:8c2e1ba7d3f4 [added version]
#     └─ layer:a3f4d9c2e1b5 [base:/tmp/demo#HEAD]

# 8. Clean up
ws drop agent-3
ws layer gc

Storage Layout

~/.ws/
├── layers/
│   ├── a3f4d9c2e1b5/          # immutable layer content
│   └── 8c2e1ba7d3f4/
├── workspaces/
│   ├── agent-1/                # mutable workspace (overlay mount on Linux)
│   └── agent-2/
├── uppers/                     # overlayfs upper dirs (Linux only)
│   ├── agent-1/
│   └── agent-2/
├── workdirs/                   # overlayfs work dirs (Linux only)
│   ├── agent-1/work/
│   └── agent-2/work/
└── meta/
    ├── layers.json             # layer metadata (parent, message, timestamp)
    └── workspaces.json         # workspace metadata (formed_from, state)

Layers are content-addressed by a SHA-256 truncated to 16 hex characters.


Platform Notes

Linux

  • Uses fuse-overlayfs for unprivileged overlay mounts — no sudo required.
  • fuse-overlayfs packages: fuse-overlayfs (Debian/Ubuntu), fuse3 (Alpine), or compile from source.
  • Each workspace = one overlay mount. Forking snapshots the source workspace to a new layer first, then mounts the new workspace from that layer.

macOS

  • By default, uses directory copies for all fork/branch operations (no kernel overlayfs available).
  • If Apple's container is installed (macOS 26+, Apple Silicon), ws auto-detects it and runs each workspace in a lightweight Linux VM (container machine) — execution and file operations happen inside the VM, the workspace directory stays visible on the Mac (see "macOS: Linux VM workspaces via Apple Container" above).
  • No additional dependencies beyond Go (copy backend).

Windows

  • Supported via the copy backend. Prebuilt binaries for Windows amd64 and arm64 are provided in each GitHub Release; extract the .tar.gz for your architecture and add the directory to your PATH.

Architecture

internal/backend/
  backend.go              — Backender interface (platform abstraction)
  copy.go                 — CopyBackend (macOS, Windows fallback)
  overlayfs_linux.go      — OverlayfsBackend (Linux, fuse-overlayfs)
  platform*.go            — Build-tag backend selection

internal/storage/
  metadata.go             — JSON metadata for layers and workspaces

cmd/ws/main.go            — CLI

Adding a new backend (e.g., container on macOS 26, APFS clone, or ZFS snapshot) requires implementing the Backender interface. The CLI, graph engine, and metadata layer are platform-agnostic.


FAQ

Q: Why not just use Git worktrees?

Git worktrees are great for human developers working on committed branches. ws is designed for agents that may have:

  • Uncommitted state that another agent wants to build on
  • Concurrent access to the same repo (no index races)
  • Need to isolate to a guaranteed-clean base, not "whatever main is now"

Q: Can I use this to replace Docker volumes or dev containers?

Not directly — ws is a filesystem primitive, not a runtime. But it's designed to compose cleanly with containers: a container runtime can mount a ws workspace as its working directory.

Q: Does ws track file renames efficiently?

Not yet — renames trigger full copy-up on the copy backend, and overlayfs handles them at the filesystem level on Linux. A Merkle-tree content-addressed backend would optimize this.

Q: How do I clean up old layers?

ws layer gc removes any layer not transitively reachable from a live workspace. Run it periodically.


Contributing

  1. Fork the repository
  2. Create a branch: git checkout -b feature/xyz
  3. Make your changes
  4. Run go test ./... and go vet ./...
  5. Submit a pull request

Please open an issue before major design changes.


Acknowledgments

Inspired by:


License

MIT — see LICENSE.

About

Workspace graphs for Git — mutable workspaces from immutable, content-addressed layers. Branch from uncommitted state without Git index races. 10 multi-agent scenarios.

Resources

Stars

2 stars

Watchers

0 watching

Forks

Releases

Packages

Contributors

Languages

0