Rendered preview

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:

Safely clone https://github.com/owner/repo.git into vendor/repo.

Pi finds git_clone_safe 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.

By default, clones are limited to 500 MiB, 10,000 files, and 60 seconds. 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.

Installation

Reference

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

Changelog.

<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`.

![git-safe demo: git_clone_safe clones a hostile repo with hooks and filters disabled, the README comes back as untrusted data, the hook never ran](assets/demo.gif)

## 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 finds `git_clone_safe` 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.

By default, clones are limited to 500 MiB, 10,000 files, and 60 seconds.
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` |
<!-- config:end -->

[Changelog](./CHANGELOG.md).