`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

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,
)