Clone an unfamiliar repository for Pi to inspect without using a raw git clone.
Use
Ask Pi to safely clone a repository into a new subdirectory, for example:
Safely clone https://github.com/owner/repo.git into vendor/repo.
Pi sees git_clone_safe and its guidance in codemode's tool list, or finds it through tool search, rather than keeping it in every tool loadout.
You can ask for a branch or only selected directories when you do not need the whole repository.
The clone is shallow and skips checkout-time hooks, credential prompts, and LFS content.
Pi checks repository size, file count, and symlinks before checkout.
Files read from a safe clone are marked as untrusted data to warn Pi against following instructions in them.
This reduces risks from unfamiliar repositories but does not establish that their contents are safe or trustworthy.
Review warnings and repository content before relying on it or running anything from it.
The tool refuses unsafe destinations and existing directories unless they are prior git-safe clones.
These extension-owned clones are disposable: cloning to the same destination replaces the previous clone after the new one succeeds.
By default, checkout content is limited to 500 MiB and 10,000 files, and the initial clone command has a 60-second timeout.
These are not hard limits on downloaded Git objects or peak disk usage.
A failed or malformed tree inspection stops checkout unless Git confirms the repository has no commits.
Each Git subprocess is stopped if combined stdout and stderr exceed 16 MiB.
Change limits only when you understand the extra disk or time you permit:
{
"git-safe": { "sizeLimitBytes": 1048576000 }
}
Invalid limits stop the clone rather than silently using a different value.
Clone size limit: Maximum checkout size in bytes; invalid limits abort cloning.
<img src="assets/banner.svg" alt="git-safe" height="70">
# git-safe
Clone an unfamiliar repository for Pi to inspect without using a raw `git clone`.

## Use
Ask Pi to safely clone a repository into a new subdirectory, for example:
```text
Safely clone https://github.com/owner/repo.git into vendor/repo.
```
Pi sees `git_clone_safe` and its guidance in codemode's tool list, or finds it through tool search, rather than keeping it in every tool loadout.
You can ask for a branch or only selected directories when you do not need the whole repository.
The clone is shallow and skips checkout-time hooks, credential prompts, and LFS content.
Pi checks repository size, file count, and symlinks before checkout.
Files read from a safe clone are marked as untrusted data to warn Pi against following instructions in them.
This reduces risks from unfamiliar repositories but does not establish that their contents are safe or trustworthy.
Review warnings and repository content before relying on it or running anything from it.
The tool refuses unsafe destinations and existing directories unless they are prior `git-safe` clones.
These extension-owned clones are disposable: cloning to the same destination replaces the previous clone after the new one succeeds.
By default, checkout content is limited to 500 MiB and 10,000 files, and the initial clone command has a 60-second timeout.
These are not hard limits on downloaded Git objects or peak disk usage.
A failed or malformed tree inspection stops checkout unless Git confirms the repository has no commits.
Each Git subprocess is stopped if combined stdout and stderr exceed 16 MiB.
Change limits only when you understand the extra disk or time you permit:
```json
{
"git-safe": { "sizeLimitBytes": 1048576000 }
}
```
Invalid limits stop the clone rather than silently using a different value.
[Installation](../../README.md#install)
## Reference
<!-- config:start -->
### Setting names
| Setting | Environment |
| --- | --- |
| `git-safe.cloneTimeoutMs` | `PI_GIT_SAFE_CLONE_TIMEOUT_MS` |
| `git-safe.fileCountLimit` | `PI_GIT_SAFE_FILE_COUNT_LIMIT` |
| `git-safe.sizeLimitBytes` | `PI_GIT_SAFE_SIZE_LIMIT_BYTES` |
#### Setting values
| Setting | Default | Valid values | Purpose |
| --- | --- | --- | --- |
| `git-safe.cloneTimeoutMs` | `60000` | Integer 1–2147483647 | Clone timeout: Maximum milliseconds for cloning; invalid limits abort cloning. |
| `git-safe.fileCountLimit` | `10000` | Integer 1–9007199254740991 | Clone file limit: Maximum checkout file count; invalid limits abort cloning. |
| `git-safe.sizeLimitBytes` | `524288000` | Integer 1–9007199254740991 | Clone size limit: Maximum checkout size in bytes; invalid limits abort cloning. |
<!-- config:end -->