# git clone: Usage, Options & Common CI Errors

> git clone copies a remote repository into a new local directory. Reference for depth, branch, and submodule flags plus the auth and shallow-clone errors.

Source: https://latchkey.dev/learn/command-reference/git-clone  
Updated: 2026-06-25

git clone creates a working copy of a remote repo and sets up origin for you.

Almost every pipeline starts by cloning. The right flags keep clones fast and avoid auth and history surprises.

## What it does

git clone copies a repository into a new directory, checks out a working copy of the default branch, and creates a remote named "origin" pointing at the source URL.

## Common usage

```Terminal
git clone https://github.com/owner/repo.git
git clone --branch v1.2.0 --single-branch https://github.com/owner/repo.git
git clone --depth 1 https://github.com/owner/repo.git
git clone --recurse-submodules https://github.com/owner/repo.git
```

## Options

| Flag | What it does |
| --- | --- |
| --depth N | Shallow clone with the last N commits |
| --branch <name> | Check out a specific branch or tag |
| --single-branch | Fetch only the named branch |
| --recurse-submodules | Clone and check out submodules too |
| --filter=blob:none | Partial clone (blobs on demand) |

## Common errors in CI

fatal: could not read Username for 'https://github.com': terminal prompts disabled - the clone needs credentials but CI has no TTY. Use a token in the URL or a credential helper, e.g. git clone https://x-access-token:${TOKEN}@github.com/owner/repo.git. For SSH, "Host key verification failed" means the host key is not in known_hosts.

## Using this in CI

CI checkouts are shallow and detached by default, which changes the answer this command gives you. Commands that read history, branch names, or tags need the checkout configured for it.

```.github/workflows/ci.yml
- uses: actions/checkout@v4
  with:
    fetch-depth: 0   # history, tags, and git describe all need this

- run: |
    git rev-parse --is-shallow-repository   # expect false
    git rev-parse --abbrev-ref HEAD          # prints HEAD when detached
```

> `git rev-parse --abbrev-ref HEAD` returns the literal string `HEAD` on a detached checkout rather than a branch name. On GitHub Actions read `github.ref_name` instead; the git command cannot know what it was checked out for.

## FAQ

### git clone: Usage, Options & Common CI Errors?

Almost every pipeline starts by cloning. The right flags keep clones fast and avoid auth and history surprises.

### What it does?

git clone copies a repository into a new directory, checks out a working copy of the default branch, and creates a remote named "origin" pointing at the source URL.

### Common errors in CI?

fatal: could not read Username for 'https://github.com': terminal prompts disabled - the clone needs credentials but CI has no TTY. Use a token in the URL or a credential helper, e.g. git clone https://x-access-token:${TOKEN}@github.com/owner/repo.git. For SSH, "Host key verification failed" means the host key is not in known_hosts.

---

Latchkey runs CI/CD that repairs its own failures. Agent entry points: https://latchkey.dev/agent.txt, https://latchkey.dev/openapi.json, https://latchkey.dev/llms.txt