> ## Documentation Index
> Fetch the complete documentation index at: https://docs.blocks.team/llms.txt
> Use this file to discover all available pages before exploring further.

# git

The `git` module is a lightweight wrapper around common git operations. For more complex operations, you can execute commands directly using the `bash` utility. Credentials are automatically configured by default.

Default configuration:

<CodeGroup>
  ```bash ~/.gitconfig theme={null}
  user.name=BlocksOrg
  user.email=bot@blocks.team
  remote.origin.url=git@github.com:YourOrg/repo.git # The remote url of the repo which triggered the agent
  ```
</CodeGroup>

## Example Usage

<CodeGroup>
  ```python python theme={null}
  from blocks import git

  # Clone a repository
  git.clone(target_dir="my-project", ref="develop")

  # Make changes and commit
  git.add(all=True)
  git.commit("Update README.md")

  # Push changes to origin
  git.push(publish=True)
  ```
</CodeGroup>

## Methods

### add

<CodeGroup>
  ```python python theme={null}
  git.add(file, all=False)
  ```
</CodeGroup>

Stages a file or files for commit. If all is True, stages all changes.

<ParamField path="file" type="string">
  File path to add (ignored if all=True).
</ParamField>

<ParamField path="all" type="bool">
  If True, adds all changes instead of a single file.
</ParamField>

### branch

<CodeGroup>
  ```python python theme={null}
  git.branch(branch_name, checkout=False)
  ```
</CodeGroup>

Creates a new branch by default. If checkout is True, creates and checks out (git checkout -b branch-name), otherwise just creates a branch with branch-name.

<ParamField path="branch_name" type="string">
  The name of the new branch.
</ParamField>

<ParamField path="checkout" type="bool">
  Whether to create and checkout the branch.
</ParamField>

### checkout

<CodeGroup>
  ```python python theme={null}
  git.checkout(target_dir="repo", ref="", new_branch=False)
  ```
</CodeGroup>

Clones a repository into `target_dir`. If `ref` is provided, it checks out that specific branch/tag.

<ParamField path="target_dir" type="string">
  The local directory for the clone.
</ParamField>

<ParamField path="ref" type="string">
  The Git ref (branch, tag) to clone. Defaults to "" (clone the default branch).
</ParamField>

<ParamField path="new_branch" type="bool">
  If True, this indicates the intention to create a new branch, but is not currently used in the command.
</ParamField>

### clone

<CodeGroup>
  ```python python theme={null}
  git.clone(target_dir="repo", ref="", new_branch=False)
  ```
</CodeGroup>

An alias for checkout, providing the same behavior for consistency.

<ParamField path="target_dir" type="string">
  The local directory for the clone.
</ParamField>

<ParamField path="ref" type="string">
  The Git ref (branch, tag) to clone. Defaults to "" (clone the default branch).
</ParamField>

<ParamField path="new_branch" type="bool">
  If True, this indicates the intention to create a new branch, but is not currently used in the command.
</ParamField>

### commit

<CodeGroup>
  ```python python theme={null}
  git.commit(message)
  ```
</CodeGroup>

Commits staged changes with a given commit message.

<ParamField path="message" type="string">
  The commit message.
</ParamField>

### init

<CodeGroup>
  ```python python theme={null}
  git.init()
  ```
</CodeGroup>

Initializes a new Git repository locally.

### pull

<CodeGroup>
  ```python python theme={null}
  git.pull()
  ```
</CodeGroup>

Pulls from the repository specified by the class’s constructed remote URL. It runs git pull origin=url HEAD.

### push

<CodeGroup>
  ```python python theme={null}
  git.push(publish=False)
  ```
</CodeGroup>

Pushes the current HEAD to the remote. If publish is True, it pushes with the -u origin HEAD flag, setting the upstream branch.

<ParamField path="publish" type="bool">
  Whether to set upstream on push.
</ParamField>