One versioned filesystem, two work surfaces.

What Git Slice gives you

Git Slice is a cloud versioned filesystem built for two real workflows. The first is direct remote work with gs fs. The second is focused local work through custom slices and fast checkouts. Both are slice-backed, both keep commit history, and both converge through the same publish model.

• Cloud reads, writes, snapshots, diffs, upload, download, and batch operations through gs fs.
• Repo bindings that import a GitHub repo into a home-slice path and optionally let you pull and push it later.
• Focused slice creation and fast gs slice checkout for editor-heavy work.
• Explicit publish and merge through gs changeset create and gs changeset merge.
• Repo browser, history, commit diffs, and slice navigation in the web app.

Understand the system before choosing a workflow

Pick the lighter surface first

gs fs mkdir /$USER/notes
gs fs write /$USER/notes/todo.md --text "ship the patch"
gs fs cat /$USER/notes/todo.md
gs fs snapshot -m "notes update"

gs slice create ui-refresh apps/web
mkdir ui-refresh && cd ui-refresh
gs slice checkout <slice-id-or-slug>
git status

The three command paths most users actually need

gs fs write /$USER/app/NOTICE.txt --text "hotfix shipped remotely"
gs fs cat /$USER/app/NOTICE.txt
gs fs snapshot -m "patch notice"

gs slice list
gs slice create ui-refresh apps/web
mkdir ui-refresh && cd ui-refresh
gs slice checkout <slice-id-or-slug>

gs repo import https://github.com/org/repo.git /$USER/vendor/repo --push-enabled
gs repo pull /$USER/vendor/repo
gs repo push /$USER/vendor/repo --message "sync upstream fixes"

gs slice sync
gs slice publish --message "refresh settings page" --files src/routes/settings.tsx
gs changeset show

Use `gs fs` when remote is the fastest path

`gs fs` operates on your home slice using absolute paths. Every mutation produces versioned history, and large transfers are deduplicated through manifest-first block exchange instead of raw full-file reupload.

Bind a GitHub repo to one directory in your home slice

Use gs repo when one absolute path in your home slice should track an upstream repository. Import a repo into a directory, pull future remote updates into that bound path, and optionally push your edits back upstream later.

gs repo import https://github.com/org/repo.git /$USER/vendor/repo --push-enabled
gs repo status /$USER/vendor/repo
gs repo pull /$USER/vendor/repo
gs repo push /$USER/vendor/repo --message "sync upstream fixes"
gs repo unlink /$USER/vendor/repo

• gs repo import snapshots the remote repo into one bound directory and records the binding.
• gs repo pull refreshes the bound directory from upstream and records a normal home-slice commit.
• gs repo push exports the bound directory back to the remote repo when push is enabled.
• The Settings page lists your current bindings so you can see path, branch, push mode, and last sync state.

Check out a focused slice instead of dragging a whole tree everywhere

A custom slice is the local-work path. Create one around the folder or surface you care about, then check it out. The client asks for manifests first and downloads only blocks missing from local cache, so repeat checkouts stay fast.

gs slice list
gs slice create ui-refresh apps/web
mkdir ui-refresh && cd ui-refresh
gs slice checkout <slice-id-or-slug>
gs slice tree
gs slice sync
gs slice publish --message "refresh settings page" --files src/routes/settings.tsx
gs changeset show

Publish local work through explicit merge steps

Changesets are the publish unit for checked-out slices. Create one from the files you changed, review it, and merge it back into the published tree. That keeps local experimentation separate from the shared state until you intentionally publish.

$EDITOR src/routes/settings.tsx
gs slice publish --message "refresh settings page" --files src/routes/settings.tsx
gs changeset show
gs changeset list --status merged

Remote `gs fs` mutations also end up on the same publish model. They create slice history immediately, and publication flows through the same merge logic instead of a separate ad hoc sync path.

Track checked-out slices globally and clean local cache state

Git Slice now keeps a global local registry of checked-out slices and their paths under your~/.gitslice state. That makes it possible to answer two practical questions quickly: which slices are checked out on this machine, and how much cached object data is still taking space.

gs slice checkouts
gs slice checkouts --slice home.$USER

gs cache stats --checkouts
gs cache prune
gs cache clear --objects

• gs slice checkouts reports how many checkouts exist globally and where they live.
• gs cache stats shows cached object count, cached bytes, tracked checkouts, and stale records.
• gs cache prune removes registry entries for deleted or invalid local worktrees.
• gs cache clear --objects wipes cached objects so you can reclaim disk when needed.
• gs doctor checks auth, current slice binding, global state, cache stats, and checkout health in one command.

Use the browser when you want visibility, not just commands

• The repo browser shows slices, folders, file previews, and commit history.
• Diff pages let you inspect commit patches and changeset patches in the browser.
• The web app defaults signed-in users to their home slice and keeps custom slices available for inspection.
• The docs page you are reading is part of the same app, so docs and product stay in one surface.

Authenticate once, then use the same identity everywhere

• Use gs login to start the OAuth device flow for the CLI.
• The web app uses cookie-backed session auth.
• Your account owns a home slice, which is why `gs fs` can work from absolute paths immediately.

Common questions