Git Clone Action - Overcut.ai

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.

Multi-Repository Support

Clone multiple repositories in a single step, either from dynamic identification or explicit specification.

Dynamic Chaining

Seamlessly chain with repo.identify to automatically clone all relevant repositories for your workflow context.

Smart Caching

Automatically uses cached repositories when possible, dramatically reducing clone time for subsequent runs.

Advanced Options

Support for shallow clones, sparse checkouts, partial clones, and more Git optimization features.

Multi-Repository Workflows

Dynamic Repository Cloning

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

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:

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:

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:

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:

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

Parameters

Required Parameters

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\}}"

Optional Parameters

string

Specific branch to checkout. If not specified, the repository’s default branch will be used. Can use template expressions like "{{trigger.pullRequest.headBranch}}".

object

Advanced Git clone configuration options for fine-grained control over the clone operation.

Clone Options

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

Depth Control

Limit the clone depth for faster downloads:

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:

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:

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"

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.

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:

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:

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.

Where to find the toggle:

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

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.

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.

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 for deeper details on how cache refresh honors this behavior.

Complete Examples

Code Review Workflow

Clone a repository for code review with optimization:

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:

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:

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:

string

required

Full path to the cloned repository in the workspace.

boolean

required

Whether the repository was loaded from cache (true) or freshly cloned (false).

boolean

required

Whether dependencies are already installed in the cached repository.

Multi-Repository Output

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

boolean

required

Overall success status. True if all repositories cloned successfully, false if any failed.

array

required

Array of individual repository clone results.

string

required

Full name of the repository that was cloned.

string

required

Full path to this repository in the workspace.

boolean

required

Whether this repository was loaded from cache.

boolean

required

Whether this specific repository clone was successful.

string

Error message if the repository clone failed.

object

required

Summary statistics for the multi-repository clone operation.

number

required

Total number of repositories attempted.

number

required

Number of repositories successfully cloned.

number

required

Number of repositories that failed to clone.

number

required

Number of repositories loaded from cache.

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:

# 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:

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

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 for the full refresh flow.

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

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

Performance Optimization

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

Multi-Repository Workflows

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

Template Usage

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

​Overview

Multi-Repository Support

Dynamic Chaining

Smart Caching

Advanced Options

​Multi-Repository Workflows

​Dynamic Repository Cloning

​Single Repository from Identification

​Basic Usage

​Simple Repository Clone

​Clone Specific Branch

​Using Dynamic Values

​Parameters

​Required Parameters

​Optional Parameters

​Clone Options

​Depth Control

​Single Branch Clone

​Sparse Checkout

​Partial Clone Filters

​Force Fresh Clone

​Submodule Clone Options

​Complete Examples

​Code Review Workflow

​Cross-Repository Bug Investigation

​Documentation Generation Across Repositories

​Output and Context

​Single Repository Output

​Multi-Repository Output

​Available Variables

​Repository Context

​Error Handling

​Partial Success in Multi-Repository Clones

​Workflow Continuation Strategies

​Caching Behavior

​Automatic Cache Usage

​Cache Compatibility

​Cache Performance

​Best Practices

​Dynamic Repository Selection

​Performance Optimization

​Multi-Repository Workflows

​Template Usage

Overview

Multi-Repository Workflows

Dynamic Repository Cloning

Single Repository from Identification

Basic Usage

Simple Repository Clone

Clone Specific Branch

Using Dynamic Values

Parameters

Required Parameters

Optional Parameters

Clone Options

Depth Control

Single Branch Clone

Sparse Checkout

Partial Clone Filters

Force Fresh Clone

Submodule Clone Options

Complete Examples

Code Review Workflow

Cross-Repository Bug Investigation

Documentation Generation Across Repositories

Output and Context

Single Repository Output

Multi-Repository Output

Available Variables

Repository Context

Error Handling

Partial Success in Multi-Repository Clones

Workflow Continuation Strategies

Caching Behavior

Automatic Cache Usage

Cache Compatibility

Cache Performance

Best Practices

Dynamic Repository Selection

Performance Optimization

Multi-Repository Workflows

Template Usage