Git Slice docs

One versioned filesystem, two work surfaces.

Use gs fs for direct cloud edits in your home slice. Use custom slices when you want a fast local checkout. Plain checkout now covers local status, diff, restore, sync, and publish on its own without local git metadata at all.

Jump to quick start

Install + login

Start with the CLI or an agent key

go install github.com/niczy/gitslice/gs@latest
gs auth keygen --out ~/.config/gitslice/agent_ed25519
gs auth login --key ~/.config/gitslice/agent_ed25519

Overview

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.

Mental model

Understand the system before choosing a workflow

Published tree

The shared repo state lives in the published tree. Git Slice stores that as the root slice and treats it as the default base for collaboration.

Home slice

Each account gets a home slice. `gs fs` works there by default through absolute paths like `/$USER/project/README.md`.

Custom slice

Create a focused slice when the job deserves a local checkout, editor workflow, tests, and a normal git-shaped working tree.

Changeset

A changeset is the explicit publish and merge unit. It is the path back into the published tree for local slice work.

Blocks + manifests

File transfer is content-addressed. Uploads and checkouts exchange manifests first and only transfer blocks your machine or the server is missing.

Quick start

Pick the lighter surface first

Cloud edit with `gs fs`

Best when you want to change remote files immediately.

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"

Custom slice checkout

Best when the task needs a local editor or tests. Plain checkout is the local workflow, with no separate git mode to manage.

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

Command map

The three command paths most users actually need

Read or patch a remote file directly

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

Best for notes, tiny fixes, and direct remote edits.

Create a focused local worktree

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 diff

Plain checkout is the local workflow. Status, diff, restore, sync, and publish all work without local git metadata.

Bind a GitHub repo into a home-slice directory

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"

Best when you want one directory to stay connected to an upstream repo while still using normal `gs fs` edits.

Publish local work back to the shared tree

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

Use this when you are ready to review and publish local slice work.

Cloud filesystem

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.

Operation	Command
Read a remote file	`gs fs cat /$USER/app/README.md`
Write a remote file	`gs fs write /$USER/app/README.md --text "hello"`
Create a checkpoint	`gs fs snapshot -m "checkpoint"`
Inspect changes	`gs fs diff <snapshot-or-commit>`
Upload a directory tree	`gs fs upload ./site /$USER/site`
Sync a directory in one command	`gs fs sync --direction push ./site /$USER/site`
Batch several mutations	`gs fs batch -f ops.jsonl`

Repo bindings

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.

Custom slices

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. Plain gs slice checkout is now the primary local path. It skips git metadata for speed, keeps a local index under .gs, and supports local status, diff, restore, sync, and publish directly. The client asks for manifests first and downloads only blocks missing from local cache, so repeat checkouts stay fast.

Create a slice around a bounded task

Use a focused name and folder scope so the slice maps cleanly to the work you plan to publish.

Check it out locally

Git Slice reconstructs the worktree from manifests plus cached and downloaded blocks, then tracks the checkout through `.gs/index`.

Sync and publish when ready

Use gs slice diff and gs slice restore for local review, gs slice sync to refresh the worktree, and gs slice publish to create or update the tracked changeset.

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 diff
gs slice restore
gs slice sync
gs slice publish --message "refresh settings page" --files src/routes/settings.tsx
gs changeset show

Changesets

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.

Local cache

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.

Inspect global checkout state

See every tracked checkout path and the slice it belongs to.

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

Inspect and clean cache state

Measure local cache usage, prune stale checkout records, or clear cached objects.

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.

Web app

Use the browser when you want visibility, not just commands

The repo browser shows slices, folders, file previews, and commit history.
Signed-in home and custom slices now support indexed file search in the browser, including regex queries and glob filters.
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.

Auth

Authenticate once, then use the same identity everywhere

Human CLI use can start with the device flow. Agent workflows should use an enrolled ed25519keypair so login stays non-interactive and machine-readable.

gs auth keygen --out ~/.config/gitslice/agent_ed25519
gs auth signup --username my-agent --email my-agent@example.com --name "My Agent" --key ~/.config/gitslice/agent_ed25519
gs auth login --key ~/.config/gitslice/agent_ed25519
gs auth status --json
gs doctor --json
gs context --json

Use gs login to start the OAuth device flow for the CLI when a human is present.
Use gs auth signup and gs auth login --key for non-interactive agent auth.
gs auth status --json, gs doctor --json, and gs context --json expose stored auth metadata including the session and enrolled agent key ID.
The web app uses cookie-backed session auth.
The Settings page shows enrolled agent keys, their fingerprints, last-used timestamps, and revoke controls.
Your account owns a home slice, which is why `gs fs` can work from absolute paths immediately.

FAQ

Common questions

When should I use `gs fs` instead of a checkout?

Use `gs fs` when the change is smaller than the setup cost of a local worktree. If you need an editor session, test loop, or lots of files, use a custom slice checkout.

What does a slice represent?

A slice is a versioned tree with its own history. Your home slice is your personal default surface. Custom slices are focused branches created for a task or folder.

Are large transfers deduplicated?

Yes. Uploads and checkouts exchange manifests first and then transfer only missing blocks. Repeated uploads and repeated checkouts get cheaper as cache coverage grows.

Does `gs fs` bypass the merge model?

No. Remote filesystem mutations create home-slice commits, and publication now goes through the same changeset merge model used by normal slice workflows.