Skip to main content
This page covers the main SDK resource APIs. For installation and configuration, see the SDK Overview.

​
Bookmarks

mesa.bookmarks manages bookmark pointers within a repository. See Versioning for how bookmarks fit into the change DAG.
  • list({ repo, ...query }) - list bookmarks in a repo
  • create({ repo, name, change_id }) - create a bookmark pointing at a change
  • delete({ repo, bookmark }) - delete a bookmark
  • move({ repo, bookmark, change_id }) - move a bookmark to a different change
  • merge({ repo, target, source, delete_source?, strategy? }) - merge source bookmark into target

​
Merging bookmarks

merge advances the target bookmark to include the history from source. The response tells you what kind of merge happened:
  • fast_forward — target was behind source; advanced without a new commit
  • merge_commit — histories diverged; a new merge commit was created
  • no_op — already up to date
You can control the merge strategy with the optional strategy field:
  • auto (default) — fast-forward when possible, merge commit when histories diverge
  • merge_commit — always create a merge commit, even when fast-forward is possible
If the merge produces file-level conflicts, the SDK throws an error with the list of conflicted paths. 
const result = await mesa.bookmarks.merge({
  repo: 'my-repo',
  target: 'main',
  source: 'feature/widgets',
  delete_source: true,
  strategy: 'merge_commit',
});

console.log(result.merge_type);    // 'fast_forward' | 'merge_commit' | 'no_op'
console.log(result.commit_oid);    // commit OID the target now points to
console.log(result.change_id);     // JJ change ID (only for 'merge_commit', null otherwise)
console.log(result.source_deleted); // true if source bookmark was deleted
Handling conflicts: 
try {
  await mesa.bookmarks.merge({
    repo: 'my-repo',
    target: 'main',
    source: 'feature/foo',
  });
} catch (err) {
  // API errors are thrown as { error: { code, message, details? } }
  const apiError = (err as any)?.error;
  if (apiError?.code === 'MERGE_CONFLICT') {
    console.log('Conflicted files:', apiError.details.conflicts);
  }
}

​
Mesa Filesystem

The SDK provides a namespace for configuring and controlling Mesa. When you mount a filesystem via mesa.fs.mount(...), the resulting MesaFileSystem also includes:
  • fs.change.new({ repo, bookmark | changeId })
  • fs.change.edit({ repo, bookmark | changeId })
  • fs.bookmark.create({ repo, name })
  • fs.bookmark.list({ repo })
For complete API details and examples, see the Filesystem API & Bash reference.

​
Git Commands

mesa.git provides the following methods:
  • clone(url, path, branch?, commitId?, username?, password?)
  • add(path, files)
  • commit(path, message, author, email, allowEmpty?)
  • push(path, username?, password?)
  • pull(path, username?, password?)
  • status(path)
  • branches(path)
  • createBranch(path, name)
  • checkoutBranch(path, branch)
  • deleteBranch(path, name)
await mesa.git.clone('https://mesa.dev/acme/repo.git', '~/repos/repo', 'main');
await mesa.git.add('~/repos/repo', ['README.md']);
await mesa.git.commit('~/repos/repo', 'Update readme', 'Mesa Bot', 'bot@mesa.dev');