Git API

The Git API provides read-only access to the project’s git repository. Use it to check the working tree status, browse commit history, list branches, and view file diffs.

Capability required: git:read

Frontend (iframe)

import { createResourceClient } from "@rightplace/sdk";

const rp = createResourceClient();
await rp.ready();

// Get current git status
const status = await rp.git.status();
// -> { initialized: true, branch: "main", changedFiles: 3, ahead: 1, ... }

// Get recent commits
const commits = await rp.git.log(20);
// -> [{ hash: "abc123", message: "Fix bug", author: "Jane", timestamp: 1713000000, ... }]

// List branches
const branches = await rp.git.branches();
// -> [{ name: "main", isCurrent: true }, { name: "feature/new-ui", isCurrent: false }]

// Get diff for a specific file
const diff = await rp.git.diff("src/index.ts");
// -> unified diff string

Backend (Node.js)

import { createResourceServer } from "@rightplace/sdk/server";

const server = createResourceServer({
  methods: {
    getRepoSummary: async (_params, { rp }) => {
      const status = await rp.git.status();
      const branches = await rp.git.branches();
      return {
        branch: status.branch,
        changedFiles: status.changedFiles,
        branchCount: branches.length,
        hasRemote: status.hasRemote,
      };
    },
  },
});

server.start();

API Reference

rp.git.status()

Returns the current git working tree status.

Parameter	Type	Description
Returns	Promise<GitStatus>	Repository status

rp.git.log(limit?)

Returns recent commits from the current branch.

Parameter	Type	Description
limit	number	Max commits to return (default: 50)
Returns	Promise<GitCommitEntry[]>	Commit list

rp.git.branches()

Returns all local branches.

Parameter	Type	Description
Returns	Promise<GitBranchEntry[]>	Branch list

rp.git.diff(filePath)

Returns a unified diff for a specific file.

Parameter	Type	Description
filePath	string	Path relative to project root
Returns	Promise<string>	Unified diff

GitStatus

Field	Type	Description
initialized	boolean	Whether git is initialized
hasRemote	boolean	Whether a remote is configured
remoteUrl	string | null	Remote origin URL
branch	string | null	Current branch name
changedFiles	number	Number of changed files
untrackedFiles	number	Number of untracked files
commitCount	number	Total commits on current branch
ahead	number	Commits ahead of remote
behind	number	Commits behind remote
changedFilePaths	GitFileEntry[]	Changed file details

GitCommitEntry

Field	Type	Description
hash	string	Full commit hash
shortHash	string	Abbreviated hash
message	string	Commit message
author	string	Author name
timestamp	number	Unix timestamp
parentHashes	string[]	Parent commit hashes

GitBranchEntry

Field	Type	Description
name	string	Branch name
isCurrent	boolean	Whether this is the active branch

GitFileEntry

Field	Type	Description
path	string	File path
status	string	Status (e.g. “modified”, “added”, “deleted”)
staged	boolean	Whether the change is staged

Manifest Configuration

{
  "capabilities": [
    "git:read"
  ]
}

Notes

• This API is read-only. Resources cannot commit, push, pull, or modify the git repository.
• The project must have a folder path set and contain a .git directory.
• Diff output uses standard unified diff format.