sgit

Standalone git / worktree CLI with a local knowledge graph — no stokd account required.

Repository: github.com/stokd-cloud/sgit
License: MIT

sgit is the public, installable product for repo navigation (sgit cd / shell scd) and offline graph scan/query. stokd optionally syncs local graph data into org cloud UI; it is not required to use sgit.

git clone https://github.com/stokd-cloud/sgit.git
cd sgit
cargo install --path crates/sgit

Or, once published on crates.io:

cargo install sgit

Ensure ~/.cargo/bin is on your PATH.

When using the stokd installer surface, sgit is also shipped alongside stokd tooling. A pure sgit install needs only this repo (or a release binary) — no mono checkout and no stokd credentials.

sgit cd resolves a repo (or worktree) and prints the path to cd into:

sgit cd owner/repo
sgit cd owner/repo main
sgit cd my-repo

Shell helper scd: source a small function that runs sgit cd and cds for you:

# ~/.zshrc or ~/.bashrc
scd() {
  local target
  target="$(sgit cd "$@")" || return $?
  cd "$target" || return $?
}

Then:

scd owner/repo
scd owner/repo feature-branch

scd is a thin shell wrapper around sgit cd. After the stokd hard-cut, scd depends on the sgit binary (not on stokd).

Two modes, chosen by the target shape (and existing local branches):

Ensures the bare + main worktree layout and prints the main worktree path (shell sgit() wrapper cds into it). Creates missing parent directories, bare-clones when needed, and re-materializes a destination that exists without a valid git connection when it is safe to do so.

sgit checkout stokd-cloud/sgit   # → /opt/worktrees/stokd-cloud/sgit/main
sgit checkout sgit               # bare name; owner resolved like clone/open

Never switches the current worktree's branch in place (pinned worktrees refuse that). Instead it:

1. Reuses an existing linked worktree already on <branch>, or
2. Creates a new sibling worktree under the configured worktree root in a folder named for the branch (slashes sanitized to dashes), then
3. Prints the absolute path (the shell sgit() wrapper cds into it).

# From any worktree of the repo (e.g. main):
sgit checkout feature/login   # → /opt/worktrees/owner/repo/feature-login
sgit checkout main            # reuses the existing main worktree

Branch source when creating:

New worktrees are pin-marked so they cannot later be repointed at another branch.

Classification while inside a git repo: existing branches and names under feature/ / task/ / project/ / fix/ / … are always branch targets. GitHub-shaped owner/repo is a repo target (falls back to a sibling branch worktree if ensure fails). Outside a git repo, every target is treated as a repo.

clone, open, and create are top-level verbs — no repo group needed:

sgit clone owner/repo        # bare clone + main worktree
sgit clone repo              # owner resolved automatically (see below)
sgit open repo               # clone if needed, then open in your editor
sgit create repo             # create on GitHub under your account + local layout

A bare repo name is resolved to a single owner by walking a chain and accepting the answer only when it is unambiguous:

1. Local layout — owners that already have the repo bare-cloned under bareRoot or checked out under root. Fully offline.
2. Your GitHub owners — your login plus the orgs you belong to. Consulted only when the local layout knows nothing, so cloning an already-provisioned repo never touches the network.

If two owners match, sgit refuses to guess and asks you to qualify:

error: repo 'widget' is ambiguous across local clones: alpha/widget, beta/widget; qualify with <owner/repo>

sgit create <name> has no chain to walk (the repo does not exist yet), so a bare name is created under your own GitHub account — matching gh repo create.

The remaining lifecycle verbs stay under the group: sgit repo list, sgit repo rename, sgit repo migrate. The old sgit repo clone|open|create spellings still work as hidden back-compat aliases.

sgit includes a local-first repo knowledge graph. Data lives under your control (default file store under ~/.sgit/graph/…, or optional Mongo). No stokd account is required.

Examples:

# Scan current repo into the default graph (file backend)
sgit graph scan --json

# Dry-run scan across configured repos
sgit graph scan --all --dry-run --json

# Inspect one repo’s components and edges
sgit graph show owner/repo --json

# Confirm storage backend (file | mongodb)
sgit graph config

~/.sgit/config.yaml (env overrides available):

graph:
  default_name: default
  storage:
    backend: file          # or mongodb
    # file:
    #   root: ~/.sgit/graph
    # mongodb:
    #   uri: mongodb://127.0.0.1:27017
    #   database: sgit_graph

Env overrides: SGIT_GRAPH_BACKEND, SGIT_GRAPH_NAME, SGIT_GRAPH_ROOT, SGIT_MONGO_URI, SGIT_MONGO_DB.

Stokd may later offer stokd graph sync to project a local/Mongo sgit graph into org storage. Day-to-day second-brain and offline workflows stay on sgit alone.

sgit/
  Cargo.toml              # workspace
  LICENSE                 # MIT
  README.md
  crates/
    sgit-core/            # library
    sgit/                 # CLI binary
    sgit-graph/           # graph engine + GraphStore trait
    sgit-graph-mongo/     # optional Mongo backend

Full crate export lands in a follow-on extraction; this bootstrap keeps a clean public home with MIT license and docs.

cargo test --workspace
cargo build -p sgit -p sgit-core

MIT — see LICENSE.