`git_clone`

git_clone ensures a project-relative destination contains a detached checkout of a requested Git revision. No external git installation is required. Clone, fetch, checkout, cleanup, and submodule progress appears in run output and UI. Pass the returned dependency to deps when another task needs the checkout.

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 use the host filesystem, network, and global Git configuration. Global url.*.insteadOf rules apply to repository and submodule URLs. SSH remotes use host known-hosts files and SSH agent. SSH config supports Hostname and Port, but not User, IdentityFile, ProxyCommand, or ProxyJump.

Git credential-helper programs are not supported. For private repositories, use SSH agent access, credentials in an HTTPS URL, or a global insteadOf rule selecting an accessible remote. Secrets embedded in URLs may be written to .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.
`deps`	No	Dependencies that must complete before cloning. Defaults to `[]`.

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, xx deletes and recreates the exported tree. 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

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

source = git_clone(
    repository="[email protected]:example/private-project.git",
    destination=".xx/src/private-project",
    revision="0123456789abcdef0123456789abcdef01234567",
    expected_commit="0123456789abcdef0123456789abcdef01234567",
    update_existing=True,
    clean=True,
    submodules=True,
)