smelt.git¶

Tier: Host - Available in every runtime, including headless mode.

Classification: Advanced - Documented low-level capability for plugins that need full control. It may evolve more freely than the Supported facade.

Asynchronous Git snapshots and explicit file-level staging. git.diff(opts?) yields separate unstaged (index to worktree, including untracked files) and staged (HEAD to index) patches. Unborn repositories use the empty tree for HEAD. git.index(diff, file, action) updates the selected file's real index entries, then acquires and indexes a fresh grouped snapshot off-thread. Mutation success is explicit (index_updated=true); if only the refresh fails, the result contains refresh_error and no diff. Retain the old snapshot as stale and refresh before another mutation. The original snapshot remains immutable.

smelt.git.diff¶

fun(opts: { cwd: string?, context: integer? }?): { root: string, branch: string, diff: smelt.diff.Diff }?, string?

Types: smelt.diff.Diff

Load separate unstaged (index to worktree) and staged (HEAD to index) changes without passing patch bodies through Lua. Yields inside smelt.spawn; cancellation terminates Git. cwd defaults to the runtime workspace and context to 3. The snapshot is stable until explicitly refreshed; a clean repository returns an empty diff.

smelt.git.index¶

fun(diff: smelt.diff.Diff, file: integer, action: "stage"|"unstage"|"toggle"): { root: string, index_updated: boolean, branch: string?, diff: smelt.diff.Diff?, refresh_error: string? }?, string?

Types: smelt.diff.Diff

Stage, unstage, or toggle one file from a Git snapshot. File indices are one-based. Toggle stages an unstaged entry and unstages a staged entry. Updates the real index, never worktree contents, then acquires and indexes both sections off the UI thread. Yields inside smelt.spawn. A successful index operation returns index_updated=true even if refresh fails: diff is then nil and refresh_error explains why. Retain the old snapshot as stale and refresh before another mutation. nil, error means the mutation did not report success; cancellation/timeouts may require refreshing to verify repository state.