Git

Provides Git operations within a Sandbox.

Constructors

new Git()

new Git(apiClient: GitApi): Git

Parameters:

apiClient GitApi

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 - Path to the Git repository root. Relative paths are resolved based on the sandbox working directory.
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 - Path to the Git repository root. Relative paths are resolved based on the sandbox working directory.

Returns:

Promise<ListBranchResponse> - List of branches in the repository

Example:

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

checkoutBranch()

checkoutBranch(path: string, branch: string): Promise<void>

Checkout branche in the repository.

Parameters:

path string - Path to the Git repository root. Relative paths are resolved based on the sandbox working directory.
branch string - Name of the branch to checkout

Returns:

Promise<void>

Example:

await git.checkoutBranch('workspace/repo', 'new-feature');

clone()

clone(
   url: string,
   path: string,
   branch?: string,
   commitId?: string,
   username?: string,
   password?: string,
   insecureSkipTls?: boolean,
depth?: number): 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 - Path where the repository should be cloned. Relative paths are resolved based on the sandbox working directory.
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
insecureSkipTls? boolean - Skip TLS certificate verification (insecure). Use only for trusted internal Git servers with self-signed or private-CA certs.
depth? number - Create a shallow clone truncated to the given number of commits.

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,
allowEmpty?: boolean): Promise<GitCommitResponse>

Commits staged changes.

Parameters:

path string - Path to the Git repository root. Relative paths are resolved based on the sandbox working directory.
message string - Commit message describing the changes
author string - Name of the commit author
email string - Email address of the commit author
allowEmpty? boolean - Allow creating an empty commit when no changes are staged

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',
  true
);

configureUser()

configureUser(
   name: string,
   email: string,
   scope?: string,
path?: string): Promise<void>

Configures the Git user name and email at the given scope.

Parameters:

name string - User name (user.name)
email string - User email (user.email)
scope? string = ‘global’ - Config scope, one of “global” (default), “local” or “system”
path? string - Repository path, required when scope is “local”

Returns:

Promise<void>

Example:

await git.configureUser('John Doe', 'john@example.com');

createBranch()

createBranch(path: string, name: string): Promise<void>

Create branch in the repository.

Parameters:

path string - Path to the Git repository root. Relative paths are resolved based on the sandbox working directory.
name string - Name of the new branch to create

Returns:

Promise<void>

Example:

await git.createBranch('workspace/repo', 'new-feature');

dangerouslyAuthenticate()

dangerouslyAuthenticate(
   username: string,
   password: string,
   host?: string,
protocol?: string): Promise<void>

Persists Git credentials globally so that subsequent operations against the given host authenticate automatically.

Parameters:

username string - Git username
password string - Git password or token
host? string - Host to authenticate against. Defaults to “github.com”
protocol? string - Protocol to authenticate against. Defaults to “https”

Returns:

Promise<void>

Remarks

This stores the password in plaintext on disk via the Git credential store.

Example:

await git.dangerouslyAuthenticate('user', 'github_token');

deleteBranch()

deleteBranch(path: string, name: string): Promise<void>

Delete branche in the repository.

Parameters:

path string - Path to the Git repository root. Relative paths are resolved based on the sandbox working directory.
name string - Name of the branch to delete

Returns:

Promise<void>

Example:

await git.deleteBranch('workspace/repo', 'new-feature');

getConfig()

getConfig(
   key: string,
   scope?: string,
path?: string): Promise<string>

Gets a Git config value at the given scope, or undefined when unset.

Parameters:

key string - Config key in dotted form (e.g. “user.name”)
scope? string = ‘global’ - Config scope, one of “global” (default), “local” or “system”
path? string - Repository path, required when scope is “local”

Returns:

Promise<string> - The config value, or undefined when the key is not set

Example:

const name = await git.getConfig('user.name');

init()

init(
   path: string,
   bare?: boolean,
initialBranch?: string): Promise<void>

Initializes a new Git repository at the specified path.

Parameters:

path string - Path where the repository should be initialized. Relative paths are resolved based on the sandbox working directory.
bare? boolean - Create a bare repository without a working tree
initialBranch? string - Name of the initial branch. If not specified, uses the Git default

Returns:

Promise<void>

Example:

await git.init('workspace/repo', false, 'main');

pull()

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

Pulls changes from the remote repository.

Parameters:

path string - Path to the Git repository root. Relative paths are resolved based on the sandbox working directory.
username? string - Git username for authentication
password? string - Git password or token for authentication
branch? string - Branch to pull. Defaults to the current branch’s upstream
remote? string - Remote to pull from. Defaults to “origin”

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'
);

// Pull a specific branch from a specific remote
await git.pull('workspace/repo', undefined, undefined, 'main', 'upstream');

push()

push(
   path: string,
   username?: string,
   password?: string,
   branch?: string,
   remote?: string,
setUpstream?: boolean): Promise<void>

Push local changes to the remote repository.

Parameters:

path string - Path to the Git repository root. Relative paths are resolved based on the sandbox working directory.
username? string - Git username for authentication
password? string - Git password or token for authentication
branch? string - Branch to push. Defaults to the current branch
remote? string - Remote to push to. Defaults to “origin”
setUpstream? boolean - Record the pushed branch as the upstream tracking branch

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'
);

// Push a new branch and set its upstream
await git.push('workspace/repo', undefined, undefined, 'feature', undefined, true);

remoteAdd()

remoteAdd(
   path: string,
   name: string,
   url: string,
   fetch?: boolean,
overwrite?: boolean): Promise<void>

Adds (or overwrites) a remote in the repository.

Parameters:

path string - Path to the Git repository root. Relative paths are resolved based on the sandbox working directory.
name string - Name of the remote
url string - URL of the remote
fetch? boolean - Fetch from the remote immediately after adding it
overwrite? boolean - Replace an existing remote with the same name

Returns:

Promise<void>

Example:

await git.remoteAdd('workspace/repo', 'origin', 'https://github.com/user/repo.git');

remoteGet()

remoteGet(path: string, name: string): Promise<string>

Gets the URL of a remote, or undefined when it does not exist.

Parameters:

path string - Path to the Git repository root. Relative paths are resolved based on the sandbox working directory.
name string - Name of the remote

Returns:

Promise<string> - The remote URL, or undefined when the remote does not exist

Example:

const url = await git.remoteGet('workspace/repo', 'origin');

remotes()

remotes(path: string): Promise<ListRemotesResponse>

Lists the remotes configured in the repository.

Parameters:

path string - Path to the Git repository root. Relative paths are resolved based on the sandbox working directory.

Returns:

Promise<ListRemotesResponse> - The configured remotes (name + URL)

Example:

const response = await git.remotes('workspace/repo');
response.remotes.forEach((r) => console.log(`${r.name}: ${r.url}`));

reset()

reset(
   path: string,
   mode?: string,
   target?: string,
files?: string[]): Promise<void>

Resets the current HEAD to the specified state.

Parameters:

path string - Path to the Git repository root. Relative paths are resolved based on the sandbox working directory.
mode? string - Reset mode, one of “soft”, “mixed” (default), “hard”, “merge” or “keep”
target? string - Revision to reset to. Defaults to HEAD
files? string[] - Constrain the reset to the given paths

Returns:

Promise<void>

Examples:

// Unstage all changes (mixed reset to HEAD)
await git.reset('workspace/repo');

// Hard reset to a previous commit
await git.reset('workspace/repo', 'hard', 'HEAD~1');

restore()

restore(
   path: string,
   files: string[],
   staged?: boolean,
   worktree?: boolean,
source?: string): Promise<void>

Restores working tree files or unstages changes.

Parameters:

path string - Path to the Git repository root. Relative paths are resolved based on the sandbox working directory.
files string[] - File paths to restore
staged? boolean - Restore the staging index for the given files
worktree? boolean - Restore the working tree for the given files. Defaults to true when neither staged nor worktree is provided
source? string - Restore file contents from the given revision instead of the index

Returns:

Promise<void>

Examples:

// Discard working tree changes
await git.restore('workspace/repo', ['file.txt']);

// Unstage changes
await git.restore('workspace/repo', ['file.txt'], true);

setConfig()

setConfig(
   key: string,
   value: string,
   scope?: string,
path?: string): Promise<void>

Sets a Git config value at the given scope.

Parameters:

key string - Config key in dotted form (e.g. “user.name”)
value string - Config value
scope? string = ‘global’ - Config scope, one of “global” (default), “local” or “system”
path? string - Repository path, required when scope is “local”

Returns:

Promise<void>

Example:

await git.setConfig('user.name', 'John Doe');

status()

status(path: string): Promise<GitStatus>

Gets the current status of the Git repository.

Parameters:

path string - Path to the Git repository root. Relative paths are resolved based on the sandbox working directory.

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