Git History API: Time Travel for App Layer History

Space Agent maintains an automatic local Git repository for every writable layer owner root — each L1/<group>/ and L2/<user>/ directory. Changes are committed automatically after a period of write quietness (10 seconds by default). The Git History API gives you programmatic access to that history: you can browse commits, inspect diffs, preview what a rollback or revert would change, and then execute the operation.

Availability and Configuration

Git history requires CUSTOMWARE_GIT_HISTORY=true (the default). When the flag is disabled, all history endpoints return errors. Use file_list or file_paths with gitRepositories: true and access: "write" to discover which owner roots have history before calling these endpoints.

Commit Schedule

The server debounces write activity before committing:

Sustained write activity	Commit delay
< 1 minute	10 seconds after last write
1–5 minutes	5 seconds after last write
5–10 minutes	1 second after last write
> 10 minutes	Immediate commit

App-file writes, deletes, copies, moves, group/user/auth writes, and module installs all schedule history for the affected owner root.

Protected Files

L2 history repos automatically ignore meta/password.json, meta/logins.json, and meta/user_crypto.json. Rollback and revert operations preserve those files rather than restoring old auth state.

Path Parameter

All history endpoints accept a path that identifies the owner root whose Git history to query. Accepted forms:

Value	Meaning
`~/`	Current user’s L2 root
`L2/<username>/`	Explicit user layer root
`L1/<group-id>/`	Group layer root

GET or POST /api/git_history_list

Lists commits for an owner root, newest first. Returns commit metadata and per-commit file action lists without loading patch bodies. Supports pagination and optional filtering by changed file path. Accepts both GET (with query params) and POST (with a JSON body).

Request

path

string

default:"~"

Logical path to the owner root, e.g. ~/, L1/team/, or L2/alice/.

limit

number

Maximum number of commits to return per page.

offset

number

Number of commits to skip from the start of the list (for pagination).

fileFilter

string

Free-text filter applied as an open-ended substring match against changed file paths or filenames. Also accepted as filter.

Response

commits

array

Ordered list of commit records (newest first).

Show Commit record fields

hash

string

Full Git commit hash.

timestamp

string

ISO 8601 commit timestamp.

message

string

Commit message generated by the server.

files

array

Per-file action entries for this commit.

Show File action fields

path

string

Logical file path.

action

string

Change type: "added", "modified", or "deleted".

currentHash

string

The current HEAD commit hash for this owner root.

hasMore

boolean

Whether there are additional commits beyond this page.

total

number

Total commit count, or null when hasMore is already known without a full scan.

{
  "path": "~/",
  "limit": 10,
  "offset": 0,
  "fileFilter": "notes"
}

GET or POST /api/git_history_diff

Returns the unified diff patch for a single file within a specific commit. Requires read permission on the owner root. This endpoint is read-only and does not modify any state. Accepts both GET (with query params) and POST (with a JSON body).

Request

path

string

default:"~"

Owner root path.

commitHash

string

required

The Git commit hash to diff. Also accepted as commit or hash.

filePath

string

required

The path of the file within the commit to diff. Also accepted as file or pathWithinCommit.

Response

patch

string

Unified diff patch for the requested file in the requested commit.

filePath

string

The resolved file path.

commitHash

string

The commit hash diffed.

{
  "path": "~/",
  "commitHash": "a1b2c3d4",
  "filePath": "L2/alice/notes.md"
}

GET or POST /api/git_history_preview

Previews the impact of a rollback ("travel") or revert operation before committing to it. Returns the list of files that would be affected. When filePath is supplied, also returns the operation-specific diff patch for that file. Requires write permission on the owner root. Accepts both GET (with query params) and POST (with a JSON body). Use this endpoint to populate a confirmation UI before calling git_history_rollback or git_history_revert.

Request

path

string

default:"~"

Owner root path.

commitHash

string

required

The commit hash to preview. Also accepted as commit or hash.

operation

string

default:"travel"

Either "travel" (preview a rollback to this commit) or "revert" (preview an inverse commit).

filePath

string

If provided, includes the operation-specific diff patch for this file in the response.

Response

affectedFiles

array

Files that would be modified, added, or deleted by the operation.

Show Affected file fields

path

string

Logical file path.

action

string

Projected change: "modified", "added", or "deleted".

patch

string

Operation-specific diff patch for filePath (only present when filePath was supplied).

operation

string

The operation that was previewed.

commitHash

string

The commit hash previewed.

{
  "path": "~/",
  "commitHash": "a1b2c3d4",
  "operation": "travel",
  "filePath": "L2/alice/notes.md"
}

POST /api/git_history_rollback

Moves the owner root’s HEAD to a specific past commit (hard reset). This is a destructive operation — the working tree is overwritten to match the target commit. The server preserves the previous HEAD as a forward-travel ref so the Time Travel UI can still navigate to future commits after going back. Protected auth files (meta/password.json, meta/logins.json, meta/user_crypto.json) are always preserved in their current state and not reset. Requires write permission on the owner root.

Rollback hard-resets the working tree. Any uncommitted changes are lost. Use /api/git_history_preview with operation: "travel" to inspect the impact first.

Request

path

string

default:"~"

Owner root path.

commitHash

string

required

The target commit hash to roll back to. Also accepted as commit or hash.

Response

action

string

Always "rolled_back".

path

string

The owner root path.

commitHash

string

The commit hash that HEAD was set to.

previousHash

string

The previous HEAD hash, preserved as a forward-travel ref.

{
  "path": "~/",
  "commitHash": "a1b2c3d4"
}

POST /api/git_history_revert

Creates a new commit that undoes the changes introduced by a specific past commit. Unlike rollback, revert does not move HEAD backwards — it adds a new forward commit with the inverse changes. This preserves the full commit history. The server uses Git-like reverse-merge semantics so later non-overlapping edits can still revert cleanly. If conflicting changes in the current worktree prevent a clean inverse apply, the endpoint returns 409 Conflict with information about the blocking file. Requires write permission on the owner root. Protected auth files are preserved.

Returns 409 when overlapping changes in the current working tree prevent the selected commit’s inverse from applying cleanly. Check the response body for the conflicting file path and current versus expected content.

Request

path

string

default:"~"

Owner root path.

commitHash

string

required

The commit hash whose changes should be undone. Also accepted as commit or hash.

Response (success)

action

string

Always "reverted".

path

string

The owner root path.

commitHash

string

The new commit hash created by the revert.

revertedHash

string

The original commit hash that was reverted.

Response (conflict — HTTP 409)

error

string

Human-readable conflict description.

conflictFile

string

The logical path of the file that caused the conflict.

currentContent

string

Current file content (when available).

expectedContent

string

The content the revert expected to find (when available).

{
  "path": "~/",
  "commitHash": "a1b2c3d4"
}

Server API

Git History API: Time Travel for App Layer History

Availability and Configuration

Commit Schedule

Protected Files

Path Parameter

GET or POST /api/git_history_list

Request

Response

GET or POST /api/git_history_diff

Request

Response

GET or POST /api/git_history_preview

Request

Response

POST /api/git_history_rollback

Request

Response

POST /api/git_history_revert

Request

Response (success)

Response (conflict — HTTP 409)

Build docs developers (and LLMs) love

Server API

Documentation Index

​Availability and Configuration

​Commit Schedule

​Protected Files

​Path Parameter

​GET or POST /api/git_history_list

​Request

​Response

​GET or POST /api/git_history_diff

​Request

​Response

​GET or POST /api/git_history_preview

​Request

​Response

​POST /api/git_history_rollback

​Request

​Response

​POST /api/git_history_revert

​Request

​Response (success)

​Response (conflict — HTTP 409)

Build docs developers (and LLMs) love

Availability and Configuration

Commit Schedule

Protected Files

Path Parameter

GET or POST /api/git_history_list

Request

Response

GET or POST /api/git_history_diff

Request

Response

GET or POST /api/git_history_preview

Request

Response

POST /api/git_history_rollback

Request

Response

POST /api/git_history_revert

Request

Response (success)

Response (conflict — HTTP 409)