SDK Quickstart

This guide assumes your application already owns a directory containing its SQLite database and files.

Install the SDK.
Terminal window
```
pnpm add @eidos.space/graft
```
Open and initialize the repository.
```
const { RepositorySession } = require("@eidos.space/graft");

const session = await RepositorySession.open(appDataRoot, {
  identity: {
    name: "Mayne",
    email: "me@example.com",
  },
});
await session.init();
```
init() creates .graft/ beside the application worktree. Call it once for a new repository. The optional identity is an in-memory session override for commit and ref identities; use configSet("user.name", ...) and configSet("user.email", ...) when the identity should be stored in the repository.
Read status.
```
const result = await session.statusIncremental();
console.log(result.status.paths);
```
Each changed path reports its repository-relative path, content kind, storage strategy, and staged or unstaged state.
Stage and commit the current application state.
```
await session.addAll();
const commit = await session.commit("initial app state");
console.log(commit);
```
addAll() captures committed SQLite transactions and app-owned files into the index. commit() advances history from that staged state.
Close the session.
```
await session.close();
```
Use try/finally in production so orderly shutdown always releases the repository runtime.

Review only the paths that changed

const status = await session.statusIncremental();
const paths = status.status.paths.map(({ path }) => path);

const diff = await session.diffPaths({
  paths,
  rows: true,
  limit: 100,
});

For a large SQLite database, request a table summary first and load rows only when the user opens a table. See the package TypeScript declarations for the complete diffSqlitePaths result types.

SDK Quickstart

Review only the paths that changed

Next