Git

Provides Git operations within a Sandbox.

Constructors

new Git()

new Git(
   sandbox: Sandbox,
   toolboxApi: ToolboxApi,
   instance: SandboxInstance): Git

Parameters:

• sandbox Sandbox
• toolboxApi ToolboxApi
• instance SandboxInstance

Returns:

• Git

Methods

add()

add(path: string, files: string[]): Promise<void>

Stages the specified files for the next commit, similar to running ‘git add’ on the command line.

Parameters:

• path string - Absolute path to the Git repository root
• files string[] - List of file paths or directories to stage, relative to the repository root

Returns:

• Promise<void>

Examples:

// Stage a single file
await git.add('/workspace/repo', ['file.txt']);

// Stage whole repository
await git.add('/workspace/repo', ['.']);

branches()

branches(path: string): Promise<ListBranchResponse>

List branches in the repository.

Parameters:

• path string - Absolute path to the Git repository root

Returns:

• Promise<ListBranchResponse> - List of branches in the repository

Example:

const response = await git.branches('/workspace/repo');
console.log(`Branches: ${response.branches}`);

clone()

clone(
   url: string,
   path: string,
   branch?: string,
   commitId?: string,
   username?: string,
password?: string): Promise<void>

Clones a Git repository into the specified path. It supports cloning specific branches or commits, and can authenticate with the remote repository if credentials are provided.

Parameters:

• url string - Repository URL to clone from
• path string - Absolute path where the repository should be cloned
• branch? string - Specific branch to clone. If not specified, clones the default branch
• commitId? string - Specific commit to clone. If specified, the repository will be left in a detached HEAD state at this commit
• username? string - Git username for authentication
• password? string - Git password or token for authentication

Returns:

• Promise<void>

Examples:

// Clone the default branch
await git.clone(
  'https://github.com/user/repo.git',
  '/workspace/repo'
);

// Clone a specific branch with authentication
await git.clone(
  'https://github.com/user/private-repo.git',
  '/workspace/private',
  branch='develop',
  username='user',
  password='token'
);

// Clone a specific commit
await git.clone(
  'https://github.com/user/repo.git',
  '/workspace/repo-old',
  commitId='abc123'
);

commit()

commit(
   path: string,
   message: string,
   author: string,
email: string): Promise<GitCommitResponse>

Commits staged changes.

Parameters:

• path string - Absolute path to the Git repository root
• message string - Commit message describing the changes
• author string - Name of the commit author
• email string - Email address of the commit author

Returns:

• Promise<GitCommitResponse>

Example:

// Stage and commit changes
await git.add('/workspace/repo', ['README.md']);
await git.commit(
  '/workspace/repo',
  'Update documentation',
  'John Doe',
  'john@example.com'
);

pull()

pull(
   path: string,
   username?: string,
password?: string): Promise<void>

Pulls changes from the remote repository.

Parameters:

• path string - Absolute path to the Git repository root
• username? string - Git username for authentication
• password? string - Git password or token for authentication

Returns:

• Promise<void>

Examples:

// Pull from a public repository
await git.pull('/workspace/repo');

// Pull from a private repository
await git.pull(
  '/workspace/repo',
  'user',
  'token'
);

push()

push(
   path: string,
   username?: string,
password?: string): Promise<void>

Push local changes to the remote repository.

Parameters:

• path string - Absolute path to the Git repository root
• username? string - Git username for authentication
• password? string - Git password or token for authentication

Returns:

• Promise<void>

Examples:

// Push to a public repository
await git.push('/workspace/repo');

// Push to a private repository
await git.push(
  '/workspace/repo',
  'user',
  'token'
);

status()

status(path: string): Promise<GitStatus>

Gets the current status of the Git repository.

Parameters:

• path string - Absolute path to the Git repository root

Returns:

• Promise<GitStatus> - Current repository status including:
  • currentBranch: Name of the current branch
  • ahead: Number of commits ahead of the remote branch
  • behind: Number of commits behind the remote branch
  • branchPublished: Whether the branch has been published to the remote repository
  • fileStatus: List of file statuses

Example:

const status = await sandbox.git.status('/workspace/repo');
console.log(`Current branch: ${status.currentBranch}`);
console.log(`Commits ahead: ${status.ahead}`);
console.log(`Commits behind: ${status.behind}`);

GitCommitResponse

Response from the git commit.

Properties:

• sha string - The SHA of the commit