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

# Git Clone Action

> Learn how to use the git.clone action to clone repositories in your Overcut workflows with advanced options for performance and customization, including multi-repository support and dynamic chaining.

The `git.clone` action is one of the most fundamental building blocks in Overcut workflows. It allows you to clone Git repositories into the workflow execution environment, providing agents and subsequent steps with access to your source code for analysis, modification, or review. With advanced multi-repository support, you can dynamically clone multiple repositories based on intelligent identification or clone them explicitly.

***

## Overview

The `git.clone` action performs Git clone operations with intelligent caching, branch management, and advanced clone options. It supports both single and multi-repository workflows, with seamless integration with the `repo.identify` action for dynamic repository selection.

<CardGroup cols={2}>
  <Card title="Multi-Repository Support" icon="list-check">
    Clone multiple repositories in a single step, either from dynamic identification or explicit specification.
  </Card>

  <Card title="Dynamic Chaining" icon="link">
    Seamlessly chain with repo.identify to automatically clone all relevant repositories for your workflow context.
  </Card>

  <Card title="Smart Caching" icon="database">
    Automatically uses cached repositories when possible, dramatically reducing clone time for subsequent runs.
  </Card>

  <Card title="Advanced Options" icon="sliders">
    Support for shallow clones, sparse checkouts, partial clones, and more Git optimization features.
  </Card>
</CardGroup>

***

## Multi-Repository Workflows

### Dynamic Repository Cloning

The most powerful pattern combines `repo.identify` with `git.clone` to automatically clone all relevant repositories:

```yaml theme={null}
steps:
  # Step 1: Identify relevant repositories
  - id: "identify-repos"
    name: "Identify Relevant Repositories"
    action: "repo.identify"
    params:
      maxResults: 3
      minConfidence: 0.7
      identificationHints: "Focus on frontend, backend, and shared libraries"
  
  # Step 2: Clone all identified repositories
  - id: "clone-repos"
    name: "Clone All Relevant Repositories"
    action: "git.clone"
    params:
      repoFullName: "{{outputs.identify-repos}}"
      branch: "main"
  
  # Step 3: Analyze across all repositories
  - id: "analyze-code"
    name: "Multi-Repository Analysis"
    action: "agent.session"
    params:
      goal: "Analyze the issue across all relevant codebases"
      instruction: "Review the code in all cloned repositories: {{outputs.identify-repos}}"
```

### Single Repository from Identification

Clone only the top-ranked repository from identification:

```yaml theme={null}
steps:
  - id: "identify-repos"
    name: "Identify Primary Repository"
    action: "repo.identify"
    params:
      maxResults: 1
      minConfidence: 0.8
  
  - id: "clone-primary"
    name: "Clone Primary Repository"
    action: "git.clone"
    params:
      repoFullName: "{{outputs.identify-repos.[0].repoFullName}}"
      branch: "{{trigger.pullRequest.headBranch}}"
```

***

## Basic Usage

### Simple Repository Clone

The most basic usage clones a repository using its default branch:

```yaml theme={null}
steps:
  - id: "clone-repo"
    name: "Clone Repository"
    action: "git.clone"
    params:
      repoFullName: "owner/repository-name"
```

### Clone Specific Branch

Clone a specific branch instead of the default:

```yaml theme={null}
steps:
  - id: "clone-repo"
    name: "Clone Repository"
    action: "git.clone"
    params:
      repoFullName: "owner/repository-name"
      branch: "feature/new-feature"
```

### Using Dynamic Values

Reference values from the trigger or previous steps:

```yaml theme={null}
steps:
  - id: "clone-repo"
    name: "Clone Repository"
    action: "git.clone"
    params:
      repoFullName: "{{trigger.repository.fullName}}"
      branch: "{{trigger.pullRequest.headBranch}}"
```

***

## Parameters

### Required Parameters

<ParamField path="repoFullName" type="string | template" required>
  Repository specification that can be:

  * **Single repository**: `"owner/repo"`
  * **Dynamic from identification**: `"{\{outputs.identify-repos\}}"` (clones all identified repositories)
  * **Specific from identification**: `"{\{outputs.identify-repos.[0].repoFullName\}}"` (clones first identified repository)
  * **Trigger-based**: `"{\{trigger.repository.fullName\}}"`
</ParamField>

### Optional Parameters

<ParamField path="branch" type="string" required={false}>
  Specific branch to checkout. If not specified, the repository's default branch will be used. Can use template expressions like `"{{trigger.pullRequest.headBranch}}"`.
</ParamField>

<ParamField path="cloneOptions" type="object" required={false}>
  Advanced Git clone configuration options for fine-grained control over the clone operation.
</ParamField>

***

## Clone Options

The `cloneOptions` parameter provides fine-grained control over the clone operation:

### Depth Control

Limit the clone depth for faster downloads:

```yaml theme={null}
steps:
  - id: "clone-repo"
    name: "Clone Repository"
    action: "git.clone"
    params:
      repoFullName: "{{outputs.identify-repos}}"
      cloneOptions:
        depth: 1  # Clone only the latest commit
```

**Available depth values:**

* `1`: Latest commit only (fastest, minimal history)
* `0`: Full history (slowest, most disk usage)
* Any positive integer for custom depth

### Single Branch Clone

Clone only the specified branch to reduce download size:

```yaml theme={null}
steps:
  - id: "clone-repo"
    name: "Clone Repository"
    action: "git.clone"
    params:
      repoFullName: "{{outputs.identify-repos}}"
      branch: "main"
      cloneOptions:
        singleBranch: true
```

### Sparse Checkout

Clone only specific directories or files:

```yaml theme={null}
steps:
  - id: "clone-repo"
    name: "Clone Repository"
    action: "git.clone"
    params:
      repoFullName: "{{outputs.identify-repos.[0].repoFullName}}"
      cloneOptions:
        sparseCheckout:
          enabled: true
          paths:
            - "src/frontend"
            - "docs"
            - "package.json"
```

<Note>
  **Cache Incompatibility**: Sparse checkout forces a full clone and cannot use repository caching, as it fundamentally changes the repository structure. This means every run will perform a fresh clone, which may be slower but ensures the correct file structure for your workflow.
</Note>

**Benefits of sparse checkout:**

* Faster downloads for large repositories
* Reduced disk space usage
* Focus on relevant code sections
* Ideal for monorepos or large projects

### Partial Clone Filters

Use Git's partial clone feature to skip large files:

```yaml theme={null}
steps:
  - id: "clone-repo"
    name: "Clone Repository"
    action: "git.clone"
    params:
      repoFullName: "{{outputs.identify-repos}}"
      cloneOptions:
        filter:
          type: "blob:none"  # Skip all file contents
```

**Available filter types:**

* `"blob:none"`: Skip all file contents (fastest, metadata only)
* `"blob:limit=100M"`: Skip files larger than 100MB
* `"combine"`: Apply multiple filters together

### Force Fresh Clone

Bypass cache and force a fresh clone:

```yaml theme={null}
steps:
  - id: "clone-repo"
    name: "Clone Repository"
    action: "git.clone"
    params:
      repoFullName: "{{outputs.identify-repos}}"
      cloneOptions:
        ignoreCache: true
```

**When to use `ignoreCache`:**

* Debugging cache-related issues
* Testing with fresh dependencies
* Ensuring latest code changes
* Troubleshooting workflow problems

### Submodule Clone Options

Workflow Builder includes explicit **Clone Submodules Recursively** and **Shallow Clone Submodules** toggles inside the Git Clone step. Enable these controls whenever the target repository depends on nested Git modules so your workflow can hydrate the entire dependency tree.

<Info>
  **Where to find the toggle**:

  1. In Workflow Builder, add or edit a **Git Clone** action.
  2. Expand **Clone Options** and switch on **Clone Submodules Recursively** to attach `--recurse-submodules` to the clone.
  3. (Optional) Enable **Shallow Clone Submodules** when you only need the most recent commits from nested repositories (adds `--shallow-submodules`).
</Info>

```yaml theme={null}
steps:
  - id: "clone-repo"
    name: "Clone Repository With Submodules"
    action: "git.clone"
    params:
      repoFullName: "owner/repository-with-submodules"
      cloneOptions:
        submodules:
          enabled: true         # Mirrors the Clone Submodules Recursively toggle
          shallow: false        # Set true to apply shallow depth to submodules
```

Set `submodules.enabled` to `true` any time your workflow needs library repos, infrastructure manifests, or shared assets that live in nested Git repositories. Combine it with `submodules.shallow` when you want faster fetches yet still need the submodule directory structure.

<Warning>
  **Access and runtime considerations**:

  * The repository token configured for the Git Clone step must have read access to every private submodule (including organization-scoped deploy keys).
  * Fetching and updating submodules adds several seconds per nested repo, so expect longer execution time for workflows that enable this option.
</Warning>

<Note>
  Cache restores respect your submodule selections. When a cached repository is extracted, Overcut replays the same submodule settings, syncing and updating nested repositories during refresh. See the [Repository Caching guide](/docs/repositories/repository-caching) for deeper details on how cache refresh honors this behavior.
</Note>

***

## Complete Examples

### Code Review Workflow

Clone a repository for code review with optimization:

```yaml theme={null}
steps:
  - id: "clone-repo"
    name: "Clone Repository"
    action: "git.clone"
    params:
      repoFullName: "{{trigger.repository.fullName}}"
      branch: "{{trigger.pullRequest.headBranch}}"
      cloneOptions:
        depth: 10
        singleBranch: true
  
  - id: "review-changes"
    name: "Multi-Repository Code Review"
    action: "agent.session"
    params:
      goal: "Review changes across all affected repositories"
      agentIds: ["senior-developer"]
      instruction: "Analyze the pull request changes in context of all affected repositories"
```

### Cross-Repository Bug Investigation

Investigate a bug that might span multiple repositories:

```yaml theme={null}
steps:
  - id: "identify-repos"
    name: "Identify Related Repositories"
    action: "repo.identify"
    params:
      maxResults: 4
      minConfidence: 0.6
      identificationHints: "Include frontend, backend, shared libraries, and database schemas"
  
  - id: "clone-repos"
    name: "Clone Investigation Repositories"
    action: "git.clone"
    params:
      repoFullName: "{{outputs.identify-repos}}"
      cloneOptions:
        depth: 50  # More history for bug investigation
        filter:
          type: "blob:limit=50M"
  
  - id: "investigate-bug"
    name: "Cross-Repository Bug Investigation"
    action: "agent.session"
    params:
      goal: "Investigate the reported bug across all relevant codebases"
      agentIds: ["debugging-agent", "senior-developer"]
      instruction: "Analyze the bug report in context of these repositories: {{outputs.identify-repos}}"
```

### Documentation Generation Across Repositories

Generate documentation from multiple related repositories:

```yaml theme={null}
steps:
  - id: "identify-repos"
    name: "Identify Documentation Repositories"
    action: "repo.identify"
    params:
      maxResults: 5
      minConfidence: 0.5
      identificationHints: "Focus on repositories with user-facing features and APIs"
  
  - id: "clone-docs"
    name: "Clone Documentation Sources"
    action: "git.clone"
    params:
      repoFullName: "{{outputs.identify-repos}}"
      cloneOptions:
        sparseCheckout:
          enabled: true
          paths:
            - "docs/"
            - "README.md"
            - "CHANGELOG.md"
            - "*.md"
            - "src/**/*.ts"  # For API documentation
  
  - id: "generate-docs"
    name: "Generate Cross-Repository Documentation"
    action: "agent.session"
    params:
      goal: "Generate comprehensive documentation across all repositories"
      instruction: "Create unified documentation from all cloned repositories"
```

***

## Output and Context

### Single Repository Output

For single repository clones, the output structure is:

<ResponseField name="workspacePath" type="string" required>
  Full path to the cloned repository in the workspace.
</ResponseField>

<ResponseField name="fromCache" type="boolean" required>
  Whether the repository was loaded from cache (true) or freshly cloned (false).
</ResponseField>

<ResponseField name="dependenciesInstalledOnCache" type="boolean" required>
  Whether dependencies are already installed in the cached repository.
</ResponseField>

### Multi-Repository Output

For multi-repository clones (when using `{{outputs.identify-repos}}`), the output structure includes:

<ResponseField name="success" type="boolean" required>
  Overall success status. True if all repositories cloned successfully, false if any failed.
</ResponseField>

<ResponseField name="repositories" type="array" required>
  Array of individual repository clone results.
</ResponseField>

<ResponseField name="repositories.[].repoFullName" type="string" required>
  Full name of the repository that was cloned.
</ResponseField>

<ResponseField name="repositories.[].workspacePath" type="string" required>
  Full path to this repository in the workspace.
</ResponseField>

<ResponseField name="repositories.[].fromCache" type="boolean" required>
  Whether this repository was loaded from cache.
</ResponseField>

<ResponseField name="repositories.[].success" type="boolean" required>
  Whether this specific repository clone was successful.
</ResponseField>

<ResponseField name="repositories.[].error" type="string" required={false}>
  Error message if the repository clone failed.
</ResponseField>

<ResponseField name="summary" type="object" required>
  Summary statistics for the multi-repository clone operation.
</ResponseField>

<ResponseField name="summary.total" type="number" required>
  Total number of repositories attempted.
</ResponseField>

<ResponseField name="summary.successful" type="number" required>
  Number of repositories successfully cloned.
</ResponseField>

<ResponseField name="summary.failed" type="number" required>
  Number of repositories that failed to clone.
</ResponseField>

<ResponseField name="summary.fromCache" type="number" required>
  Number of repositories loaded from cache.
</ResponseField>

### Available Variables

Use these variables in subsequent steps:

**Single Repository:**

* **`{{outputs.clone-repo.workspacePath}}`**: Full path to the cloned repository
* **`{{outputs.clone-repo.fromCache}}`**: Whether cache was used
* **`{{outputs.clone-repo.dependenciesInstalledOnCache}}`**: Whether dependencies are already installed

**Multi-Repository:**

* **`{{outputs.clone-repos.success}}`**: Overall clone success status
* **`{{outputs.clone-repos.repositories}}`**: Array of all repository results
* **`{{outputs.clone-repos.summary.successful}}`**: Count of successful clones
* **`{{outputs.clone-repos.summary.failed}}`**: Count of failed clones

### Repository Context

All cloned repositories are automatically added to the workflow context and available to agents:

* **Repository Information**: Name, provider, organization
* **File System Access**: Full read/write access to repository contents
* **Git Operations**: Access to commit history, branches, and Git metadata
* **Dependency Management**: Automatic detection and installation of dependencies (when caching is enabled)

***

## Error Handling

### Partial Success in Multi-Repository Clones

When cloning multiple repositories, some may succeed while others fail. The action handles this gracefully:

```yaml theme={null}
# Example output for partial success
{
  "success": false,  # Overall false because some repos failed
  "repositories": [
    {
      "repoFullName": "owner/frontend",
      "workspacePath": "/workspace/frontend",
      "success": true,
      "fromCache": true
    },
    {
      "repoFullName": "owner/backend", 
      "workspacePath": "",
      "success": false,
      "error": "Repository not found or access denied"
    }
  ],
  "summary": {
    "total": 2,
    "successful": 1,
    "failed": 1,
    "fromCache": 1
  }
}
```

### Workflow Continuation Strategies

Handle clone failures gracefully in your workflows:

```yaml theme={null}
steps:
  - id: "clone-repos"
    name: "Clone Repositories"
    action: "git.clone"
    params:
      repoFullName: "{{outputs.identify-repos}}"
  
  - id: "analyze-available"
    name: "Analyze Available Repositories"
    action: "agent.session"
    params:
      goal: "Analyze the issue using available repositories"
      instruction: |
        Clone summary: {{outputs.clone-repos.summary.successful}} of {{outputs.clone-repos.summary.total}} repositories available.
        
        Focus your analysis on the successfully cloned repositories.
        If critical repositories failed to clone, mention this limitation in your analysis.
```

***

## Caching Behavior

### Automatic Cache Usage

Overcut automatically uses cached repositories when possible:

* **Cache Eligibility**: Determined by clone options and repository configuration
* **Cache Refresh**: Automatic background refresh every 10 days
* **Cache Invalidation**: Stale caches (20+ days) are ignored
* **Non-blocking**: Cache operations never block workflow execution
* **Multi-Repository**: Each repository in a multi-repo clone is cached independently

<Note>
  When the Git Clone step enables the submodule toggles, cached clones keep every nested repository in sync during refresh. Overcut replays `git submodule sync --recursive && git submodule update --recursive` with the same depth settings used at clone time so cache restores match fresh clones. See [Repository Caching](/docs/repositories/repository-caching#how-overcut-updates-cached-repositories) for the full refresh flow.
</Note>

### Cache Compatibility

| Clone Option        | Cache Compatible |
| ------------------- | ---------------- |
| `depth`             | ✅ Yes            |
| `singleBranch`      | ✅ Yes            |
| `filter`            | ✅ Yes            |
| `sparseCheckout`    | ❌ No             |
| `ignoreCache: true` | ❌ No             |

### Cache Performance

* **First Run**: Normal clone time (creates cache for each repository)
* **Subsequent Runs**: 90%+ faster using cache
* **Cache Hit Rate**: Typically 95%+ for active repositories
* **Multi-Repository**: Cache hits are independent per repository
* **Background Refresh**: Automatic updates without blocking workflows

***

## Best Practices

### Dynamic Repository Selection

1. **Use `repo.identify` first**: Always identify repositories dynamically rather than hardcoding
2. **Set appropriate confidence thresholds**: Use `minConfidence: 0.7+` for critical operations
3. **Provide identification hints**: Help the AI make better repository selections
4. **Handle partial failures**: Design workflows to continue even if some repositories fail to clone

### Performance Optimization

1. **Use shallow clones**: Set `depth: 1` for faster clones when full history isn't needed
2. **Enable single branch**: Use `singleBranch: true` to reduce download size
3. **Leverage caching**: Avoid `ignoreCache: true` unless necessary
4. **Filter large files**: Use `filter` options for repositories with large binary files

### Multi-Repository Workflows

1. **Clone in parallel**: The action automatically clones multiple repositories in parallel for better performance
2. **Check success status**: Always verify `{{outputs.clone-repos.success}}` before proceeding
3. **Use summary statistics**: Leverage `{{outputs.clone-repos.summary}}` for workflow decisions
4. **Handle individual failures**: Design agents to work with partial repository sets

### Template Usage

1. **Use full output for multi-repo**: `{{outputs.identify-repos}}` for all identified repositories
2. **Use indexed access for single repo**: `{{outputs.identify-repos.[0].repoFullName}}` for just the top result
3. **Combine with conditionals**: Use template logic to handle different scenarios
4. **Pass context to agents**: Include repository information in agent instructions