---
title: git_clone
description: Materialize a pinned Git source tree with host Git configuration and access.
---

# `git_clone`

`git_clone` ensures a project-relative destination contains a detached checkout of a requested Git revision. It uses go-git v6 directly; an external `git` executable is not required. The function registers a root task, shows clone/fetch/checkout progress in the run UI, and returns a dependency.

During clone and fetch, go-git's remote sideband progress is forwarded unchanged to run output and its latest status line is shown in the Git task row. Local work reports status phases such as checkout, clean, and submodule update. Unknown totals are not presented as synthetic percentages.

Prefer a full SHA-1 or SHA-256 commit ID as `revision` or `expected_commit`. Branches, tags, and `HEAD` can move between runs and are not deterministic build inputs.

## Host access

Git operations run with full host filesystem and network access, outside xx's virtual task environment. go-git reads host global Git config. Global `url.*.insteadOf` rules are applied to repository and recursively discovered submodule URLs. SSH remotes use host known-hosts files and SSH agent; go-git reads `Hostname` and `Port` from host SSH config but does not honor common OpenSSH settings such as `User`, `IdentityFile`, `ProxyCommand`, or `ProxyJump`.

go-git does not invoke Git credential-helper programs. For private HTTPS remotes, use a URL/authentication method supported directly by go-git or a global `insteadOf` rule that selects an accessible SSH remote. Secrets embedded in URLs may be persisted in `.git/config`; avoid them when possible.

## Arguments

| Argument | Required | Description |
| --- | --- | --- |
| `repository` | Yes | Remote URL or local repository path. Relative local paths resolve from project root. |
| `destination` | Yes | Project-relative destination directory. |
| `revision` | No | Revision to check out detached. Defaults to `expected_commit` when provided, otherwise `HEAD`. |
| `expected_commit` | No | Full 40-character SHA-1 or 64-character SHA-256 commit ID. Fails when `revision` resolves elsewhere. |
| `update_existing` | No | Fetch `origin` and tags using requested depth before resolving revision. Defaults to `False`. Existing clones can still be reused without network access when they already contain requested revision. |
| `clean` | No | Discard tracked changes and remove untracked files and directories after checkout. Defaults to `False`. |
| `remove_git_dir` | No | Remove `.git` after successful verification. Requires `clean=True`. Defaults to `False`. |
| `submodules` | No | Initialize and recursively update submodules. Defaults to `False`. |
| `depth` | No | Positive shallow-fetch depth. |
| `sparse_paths` | No | Repository-relative directories to materialize through sparse checkout. Defaults to all paths. |
| `filter` | No | Reserved for future partial-checkout support. Any non-empty value currently fails because go-git cannot materialize omitted objects into a source tree. |

## Destructive behavior

`clean=True` discards local tracked changes and removes untracked files under `destination`. `remove_git_dir=True` exports a source tree without repository metadata. On later runs, that exported tree is recursively deleted and recreated because its commit can no longer be verified. Do not point either option at a directory containing work you need.

Project root cannot be used with `clean=True, remove_git_dir=True`; destructive replacement requires a child destination.

An existing Git repository is reused only when its `origin` URL matches the requested repository after global URL rewriting. A non-empty non-repository destination is rejected, except exported trees recreated by `clean=True, remove_git_dir=True`.

## Example

```starlark
load("@git@1", "git_clone")

source = git_clone(
    repository="git@github.com:example/private-project.git",
    destination=".xx/src/private-project",
    revision="0123456789abcdef0123456789abcdef01234567",
    expected_commit="0123456789abcdef0123456789abcdef01234567",
    update_existing=True,
    clean=True,
    submodules=True,
)
```

<!--
Sitemap

URL: https://withxx.dev/index.md
Title: xx
Description: Practical, reproducible builds without build-system ceremony

URL: https://withxx.dev/examples/commands.md
Title: Command Examples
Description: General command, environment, and entrypoint patterns.

URL: https://withxx.dev/examples/go.md
Title: Go Examples
Description: Common Go build patterns with managed SDKs.

URL: https://withxx.dev/examples/nodejs.md
Title: Node.js Examples
Description: Common Node.js task patterns with a managed distribution.

URL: https://withxx.dev/examples/zig.md
Title: Zig Examples
Description: Direct Zig commands and Go CGO builds with a managed Zig distribution.

URL: https://withxx.dev/load.md
Title: Loading Files
Description: Split xx configuration into local Starlark modules.

URL: https://withxx.dev/packages/git/git_clone.md
Title: git_clone
Description: Materialize a pinned Git source tree with host Git configuration and access.

URL: https://withxx.dev/packages/git/git_init_repository.md
Title: git_init_repository
Description: Ensure an empty SHA-1 or SHA-256 Git repository exists.

URL: https://withxx.dev/packages/go/go.md
Title: go
Description: Activate a managed Go SDK for dependent tasks.

URL: https://withxx.dev/packages/go/go_binary.md
Title: go_binary
Description: Build a Go command with a managed SDK.

URL: https://withxx.dev/packages/go/go_install.md
Title: go_install
Description: Install a versioned Go command for dependent tasks.

URL: https://withxx.dev/packages/go/go_protobuf.md
Title: go_protobuf
Description: Install protoc-gen-go and provide it as a Protobuf generator.

URL: https://withxx.dev/packages/go/go_run.md
Title: go_run
Description: Run a local program or versioned Go command with a managed SDK.

URL: https://withxx.dev/packages/go/go_test.md
Title: go_test
Description: Test Go packages with a managed SDK.

URL: https://withxx.dev/packages/nodejs/nodejs.md
Title: nodejs
Description: Activate managed Node.js for dependent tasks.

URL: https://withxx.dev/packages/nodejs/npm_install.md
Title: npm_install
Description: Install project dependencies with managed npm.

URL: https://withxx.dev/packages/nodejs/npm_run.md
Title: npm_run
Description: Run a project package script with managed npm.

URL: https://withxx.dev/packages/nodejs/npx_run.md
Title: npx_run
Description: Run a versioned npm package command with managed npx.

URL: https://withxx.dev/packages/os/env_append.md
Title: env_append
Description: Append an item to a list-like environment variable.

URL: https://withxx.dev/packages/os/env_get.md
Title: env_get
Description: Read a value from a task environment while evaluating Starlark.

URL: https://withxx.dev/packages/os/env_prepend.md
Title: env_prepend
Description: Prepend an item to a list-like environment variable.

URL: https://withxx.dev/packages/os/env_set.md
Title: env_set
Description: Set an environment variable for dependent tasks.

URL: https://withxx.dev/packages/os/env_unset.md
Title: env_unset
Description: Remove an environment variable from dependent tasks.

URL: https://withxx.dev/packages/os/run.md
Title: run
Description: Run a command from the project root.

URL: https://withxx.dev/packages/protobuf/protobuf_generate.md
Title: protobuf_generate
Description: Generate source code with a managed Protobuf compiler.

URL: https://withxx.dev/packages/protobuf/protobuf_generator.md
Title: protobuf_generator
Description: Adapt an installed protoc plugin dependency for code generation.

URL: https://withxx.dev/packages/protobuf/protoc.md
Title: protoc
Description: Activate a managed Protobuf compiler for dependent tasks.

URL: https://withxx.dev/packages/zig/zig.md
Title: zig
Description: Activate managed Zig for dependent tasks.

URL: https://withxx.dev/packages/zig/zig_cc.md
Title: zig_cc
Description: Configure managed Zig as a C and C++ compiler.

URL: https://withxx.dev/packages.md
Title: Built-in Packages
Description: Versioned toolchains, commands, and task environment helpers provided by xx.
-->