Luigit
repositories / pi-ext

pi-ext

bugabingas pi extensions

owned by admin

extensions/git-safe/README.md

Raw
Rendered preview
git-safe

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

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.

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

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