# Git Workspaces and Patch Extraction

How DynoCap imports Git repositories, sanitizes histories and hooks, and extracts clean, verifiable patches.

HTML: https://dynocap.dev/docs/explanation/git-workspaces-and-patches

For AI coding agents to be effective, they need Git: they need to inspect commit history, view `git log`, run `git diff`, and understand repository structure.

However, copying a host `.git` folder directly into an untrusted environment creates serious security and integrity issues. This document explains how DynoCap imports repositories safely and extracts clean patches.

---

## 1. Sanitized History Import

When you run `dynocap clone ./project my-task`, the `dynocap-workspace` companion tool performs a **sanitized Git import**:

1. **Local Object Packing:** It extracts commits, trees, and blobs from your local Git object database without exposing host configuration files.
2. **Alternates & Borrowed Objects:** If your host repository uses shared Git alternates or worktrees, `dynocap-workspace` resolves borrowed objects and copies them into the guest's standalone repository so the sandbox never attempts to read host object stores.
3. **Hook Disabling:** Host Git hooks (`.git/hooks/*`, such as pre-commit or post-checkout scripts) are deliberately **not imported**. This prevents malicious repositories from triggering arbitrary host hook scripts during import.
4. **Only the History You Choose:** Sandbox code can read everything imported and, on `filtered` or `nat`, send it out. So the import keeps only refs and the objects they reach:
   - `--history branches` (the default): local branches, tags and remote-tracking refs.
   - `--history head`: only the history of the checked-out commit.
   - `--history none`: files only; the sandbox has no Git repository.

   Every mode drops the stash, reflogs, `refs/original` (filter-branch backups), notes and other refs, other worktrees' metadata, submodule repositories in `.git/modules`, merge and rebase pseudo-refs, and every object nothing references any more, so a secret removed from history does not come back in the sandbox. A secret still reachable from a kept branch or tag is imported; use `head` or `none` when other branches hold work the sandbox should not see.

5. **Clean Baseline:** The imported HEAD commit and uncommitted working directory state are recorded as the baseline commit inside the guest.

---

## 2. In-Guest Git Operations

Inside `/workspace` in the guest:

- Git is pre-installed in the runtime disk.
- The coding agent can execute standard Git inspection commands:
  ```sh
  git status
  git diff
  git log -n 5
  git blame src/index.js
  ```
- The agent can make edits, stage files, or create local commits as needed.

---

## 3. Patch Extraction & Review

When `dynocap finish` is invoked:

1. The host companion queries the guest disk for changes between the imported baseline and the final state of `/workspace`.
2. `.git` internal metadata is strictly excluded from the review: the patch reflects only source code modifications, new files, and file deletions.
3. A unified diff patch (`changes.patch`) is generated and verified using standard Git diff algorithms.
4. Full copies of all modified files are exported to `~/.dynocap/tasks/<id>/result/changes/`.

---

## 4. Applying Patches on the Host

DynoCap does not automatically patch your local files. Instead, it provides a safe, standard command string:

```sh
git apply --check '<patch-path>' && git apply '<patch-path>'
```

- `git apply --check` verifies that the patch applies cleanly against your current working tree without conflicts or whitespace errors.
- `git apply` applies the modifications directly to your working tree.

This explicit two-step pattern ensures that a human developer or supervising workflow has final authority before changes merge into your active host repository.