--- title: "Git" hideTitleOnPage: true --- ## Git Provides Git operations within a Sandbox. ### Constructors #### new Git() ```ts new Git(apiClient: GitApi): Git ``` **Parameters**: - `apiClient` _GitApi_ **Returns**: - `Git` ### Methods #### add() ```ts add(path: string, files: string[]): Promise ``` 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` **Examples:** ```ts // Stage a single file await git.add('workspace/repo', ['file.txt']); ``` ```ts // Stage whole repository await git.add('workspace/repo', ['.']); ``` *** #### branches() ```ts branches(path: string): Promise ``` 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` - List of branches in the repository **Example:** ```ts const response = await git.branches('workspace/repo'); console.log(`Branches: ${response.branches}`); ``` *** #### checkoutBranch() ```ts checkoutBranch(path: string, branch: string): Promise ``` 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` **Example:** ```ts await git.checkoutBranch('workspace/repo', 'new-feature'); ``` *** #### clone() ```ts clone( url: string, path: string, branch?: string, commitId?: string, username?: string, password?: string): Promise ``` 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 **Returns**: - `Promise` **Examples:** ```ts // Clone the default branch await git.clone( 'https://github.com/user/repo.git', 'workspace/repo' ); ``` ```ts // Clone a specific branch with authentication await git.clone( 'https://github.com/user/private-repo.git', 'workspace/private', branch='develop', username='user', password='token' ); ``` ```ts // Clone a specific commit await git.clone( 'https://github.com/user/repo.git', 'workspace/repo-old', commitId='abc123' ); ``` *** #### commit() ```ts commit( path: string, message: string, author: string, email: string, allowEmpty?: boolean): Promise ``` 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` **Example:** ```ts // Stage and commit changes await git.add('workspace/repo', ['README.md']); await git.commit( 'workspace/repo', 'Update documentation', 'John Doe', 'john@example.com', true ); ``` *** #### createBranch() ```ts createBranch(path: string, name: string): Promise ``` 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` **Example:** ```ts await git.createBranch('workspace/repo', 'new-feature'); ``` *** #### deleteBranch() ```ts deleteBranch(path: string, name: string): Promise ``` 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` **Example:** ```ts await git.deleteBranch('workspace/repo', 'new-feature'); ``` *** #### pull() ```ts pull( path: string, username?: string, password?: string): Promise ``` 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 **Returns**: - `Promise` **Examples:** ```ts // Pull from a public repository await git.pull('workspace/repo'); ``` ```ts // Pull from a private repository await git.pull( 'workspace/repo', 'user', 'token' ); ``` *** #### push() ```ts push( path: string, username?: string, password?: string): Promise ``` 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 **Returns**: - `Promise` **Examples:** ```ts // Push to a public repository await git.push('workspace/repo'); ``` ```ts // Push to a private repository await git.push( 'workspace/repo', 'user', 'token' ); ``` *** #### status() ```ts status(path: string): Promise ``` 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` - 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:** ```ts 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