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.

​
Overview

The git.clone action performs a Git clone operation with intelligent caching, branch management, and advanced clone options. It’s designed to be fast, reliable, and configurable for different use cases.

Smart Caching

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

Branch Management

Clone specific branches or use the repository’s default branch with automatic checkout.

Advanced Options

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

Error Handling

Robust error handling with detailed logging and fallback mechanisms.

​
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

​
repoFullName
string
required
Organization/Repository full name in “owner/repo” format. This is the only required parameter for the git.clone action.

​
Optional Parameters

​
branch
string
Specific branch to checkout. If not specified, the repository’s default branch will be used.
​
cloneOptions
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: "owner/repository-name"
      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: "owner/repository-name"
      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: "owner/repository-name"
      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: "owner/repository-name"
      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: "owner/repository-name"
      cloneOptions:
        ignoreCache: true
When to use ignoreCache:
  • Debugging cache-related issues
  • Testing with fresh dependencies
  • Ensuring latest code changes
  • Troubleshooting workflow problems

​
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
        filter:
          type: "blob:limit=50M"

​
Documentation Generation

Clone only documentation-related files: 
steps:
  - id: "clone-docs"
    name: "Clone Documentation"
    action: "git.clone"
    params:
      repoFullName: "{{trigger.repository.fullName}}"
      cloneOptions:
        sparseCheckout:
          enabled: true
          paths:
            - "docs/"
            - "README.md"
            - "CHANGELOG.md"
            - "*.md"

​
Large Repository Analysis

Optimize for large repositories with partial cloning: 
steps:
  - id: "clone-large-repo"
    name: "Clone Large Repository"
    action: "git.clone"
    params:
      repoFullName: "{{trigger.repository.fullName}}"
      cloneOptions:
        depth: 1
        singleBranch: true
        filter:
          type: "blob:limit=100M"
        ignoreCache: false

​
Caching Behavior

​
Automatic Cache Usage

Overcut automatically uses cached repositories when possible:
  • Cache Eligibility: Determined by clone options
  • Cache Refresh: Automatic background refresh every 10 days
  • Cache Invalidation: Stale caches (20+ days) are ignored
  • Non-blocking: Cache operations never block workflow execution

​
Cache Compatibility

Clone OptionCache Compatible
depth✅ Yes
singleBranch✅ Yes
filter✅ Yes
sparseCheckout❌ No
ignoreCache: true❌ No

​
Cache Performance

  • First Run: Normal clone time (creates cache)
  • Subsequent Runs: 90%+ faster using cache
  • Cache Hit Rate: Typically 95%+ for active repositories
  • Background Refresh: Automatic updates without blocking workflows

​
Output and Context

​
Step Output

The git.clone action provides output that can be used by subsequent steps:
​
workspacePath
string
required
Full path to the cloned repository in the workspace.
​
fromCache
boolean
required
Whether the repository was loaded from cache (true) or freshly cloned (false).
​
dependenciesInstalledOnCache
boolean
required
Whether dependencies are already installed in the cached repository.

​
Available Variables

Use these variables in subsequent steps:
  • {{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

​
Repository Context

The cloned repository is automatically added to the workflow context:
  • Repository Information: Name, provider, organization
  • Authentication: Automatic token management
  • Correlations: Links to related tickets and issues
  • Secrets: Repository-specific environment variables

​
Error Handling

​
Common Errors

​
Repository full name is required
error
required
Missing repoFullName parameter. Ensure repoFullName is set in your workflow step.
​
Branch not found
error
required
Specified branch doesn’t exist. Check branch name or use the repository’s default branch.
​
Permission denied
error
required
Insufficient repository access. Verify repository permissions and authentication.
​
Clone timeout
error
required
Large repository or slow network. Use depth limits or filters to optimize.

​
Best Practices

​
General Guidelines

  1. Always specify repoFullName: Use the full “owner/repo” format
  2. Use appropriate depth: Balance between speed and history needs
  3. Leverage caching: Don’t use ignoreCache unless necessary
  4. Consider sparse checkout: For workflows that only need specific files
  5. Monitor performance: Use logs to identify optimization opportunities

​
Next Steps

Now that you understand the git.clone action, explore these related topics: Ready to optimize your workflows? Start by analyzing your current clone operations and applying the appropriate optimization strategies.