Git

Git

class Git()

Provides Git operations within a Sandbox.

Example:

# Clone a repository
sandbox.git.clone(
    url="https://github.com/user/repo.git",
    path="workspace/repo"
)

# Check repository status
status = sandbox.git.status("workspace/repo")
print(f"Modified files: {status.modified}")

# Stage and commit changes
sandbox.git.add("workspace/repo", ["file.txt"])
sandbox.git.commit(
    path="workspace/repo",
    message="Update file",
    author="John Doe",
    email="[email protected]"
)

Git.__init__

def __init__(api_client: GitApi)

Initializes a new Git handler instance.

Arguments:

• api_client GitApi - API client for Sandbox Git operations.

Git.add

@intercept_errors(message_prefix="Failed to add files: ")
@with_instrumentation()
def add(path: str, files: list[str]) -> None

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

Arguments:

• path str - Path to the Git repository root. Relative paths are resolved based on the sandbox working directory.
• files list[str] - List of file paths or directories to stage, relative to the repository root.

Example:

# Stage a single file
sandbox.git.add("workspace/repo", ["file.txt"])

# Stage multiple files
sandbox.git.add("workspace/repo", [
    "src/main.py",
    "tests/test_main.py",
    "README.md"
])

Git.branches

@intercept_errors(message_prefix="Failed to list branches: ")
@with_instrumentation()
def branches(path: str) -> ListBranchResponse

Lists branches in the repository.

Arguments:

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

Returns:

• ListBranchResponse - List of branches in the repository.

Example:

response = sandbox.git.branches("workspace/repo")
print(f"Branches: {response.branches}")

Git.clone

@intercept_errors(message_prefix="Failed to clone repository: ")
@with_instrumentation()
def clone(url: str,
          path: str,
          branch: str | None = None,
          commit_id: str | None = None,
          username: str | None = None,
          password: str | None = None) -> None

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.

Arguments:

• url str - Repository URL to clone from.
• path str - Path where the repository should be cloned. Relative paths are resolved based on the sandbox working directory.
• branch str | None - Specific branch to clone. If not specified, clones the default branch.
• commit_id str | None - Specific commit to clone. If specified, the repository will be left in a detached HEAD state at this commit.
• username str | None - Git username for authentication.
• password str | None - Git password or token for authentication.

Example:

# Clone the default branch
sandbox.git.clone(
    url="https://github.com/user/repo.git",
    path="workspace/repo"
)

# Clone a specific branch with authentication
sandbox.git.clone(
    url="https://github.com/user/private-repo.git",
    path="workspace/private",
    branch="develop",
    username="user",
    password="token"
)

# Clone a specific commit
sandbox.git.clone(
    url="https://github.com/user/repo.git",
    path="workspace/repo-old",
    commit_id="abc123"
)

Git.commit

@intercept_errors(message_prefix="Failed to commit changes: ")
@with_instrumentation()
def commit(path: str,
           message: str,
           author: str,
           email: str,
           allow_empty: bool = False) -> GitCommitResponse

Creates a new commit with the staged changes. Make sure to stage changes using the add() method before committing.

Arguments:

• path str - Path to the Git repository root. Relative paths are resolved based on the sandbox working directory.
• message str - Commit message describing the changes.
• author str - Name of the commit author.
• email str - Email address of the commit author.
• allow_empty bool, optional - Allow creating an empty commit when no changes are staged. Defaults to False.

Example:

# Stage and commit changes
sandbox.git.add("workspace/repo", ["README.md"])
sandbox.git.commit(
    path="workspace/repo",
    message="Update documentation",
    author="John Doe",
    email="[email protected]",
    allow_empty=True
)

Git.push

@intercept_errors(message_prefix="Failed to push changes: ")
@with_instrumentation()
def push(path: str,
         username: str | None = None,
         password: str | None = None) -> None

Pushes all local commits on the current branch to the remote repository. If the remote repository requires authentication, provide username and password/token.

Arguments:

• path str - Path to the Git repository root. Relative paths are resolved based on the sandbox working directory.
• username str | None - Git username for authentication.
• password str | None - Git password or token for authentication.

Example:

# Push without authentication (for public repos or SSH)
sandbox.git.push("workspace/repo")

# Push with authentication
sandbox.git.push(
    path="workspace/repo",
    username="user",
    password="github_token"
)

Git.pull

@intercept_errors(message_prefix="Failed to pull changes: ")
@with_instrumentation()
def pull(path: str,
         username: str | None = None,
         password: str | None = None) -> None

Pulls changes from the remote repository. If the remote repository requires authentication, provide username and password/token.

Arguments:

• path str - Path to the Git repository root. Relative paths are resolved based on the sandbox working directory.
• username str | None - Git username for authentication.
• password str | None - Git password or token for authentication.

Example:

# Pull without authentication
sandbox.git.pull("workspace/repo")

# Pull with authentication
sandbox.git.pull(
    path="workspace/repo",
    username="user",
    password="github_token"
)

Git.status

@intercept_errors(message_prefix="Failed to get status: ")
@with_instrumentation()
def status(path: str) -> GitStatus

Gets the current Git repository status.

Arguments:

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

Returns:

• GitStatus - Repository status information including:
  • current_branch: Current branch name
  • file_status: List of file statuses
  • ahead: Number of local commits not pushed to remote
  • behind: Number of remote commits not pulled locally
  • branch_published: Whether the branch has been published to the remote repository

Example:

status = sandbox.git.status("workspace/repo")
print(f"On branch: {status.current_branch}")
print(f"Commits ahead: {status.ahead}")
print(f"Commits behind: {status.behind}")

Git.checkout_branch

@intercept_errors(message_prefix="Failed to checkout branch: ")
@with_instrumentation()
def checkout_branch(path: str, branch: str) -> None

Checkout branch in the repository.

Arguments:

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

Example:

# Checkout a branch
sandbox.git.checkout_branch("workspace/repo", "feature-branch")

Git.create_branch

@intercept_errors(message_prefix="Failed to create branch: ")
@with_instrumentation()
def create_branch(path: str, name: str) -> None

Create branch in the repository.

Arguments:

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

Example:

# Create a new branch
sandbox.git.create_branch("workspace/repo", "new-feature")

Git.delete_branch

@intercept_errors(message_prefix="Failed to delete branch: ")
@with_instrumentation()
def delete_branch(path: str, name: str) -> None

Delete branch in the repository.

Arguments:

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

Example:

# Delete a branch
sandbox.git.delete_branch("workspace/repo", "old-feature")

GitCommitResponse

class GitCommitResponse()

Response from the git commit.

Attributes:

• sha str - The SHA of the commit