# Файлы и Git

Файловая система песочницы — общее рабочее пространство для браузерных изменений, команд, компонентов подготовки и Git. Для непосредственного просмотра используйте вкладку *Файлы*, для автоматизации — REST API файлов, а после клонирования запускайте обычные Git-команды.

## Выбор интерфейса[​](#choose-the-right-surface "Прямая ссылка на Выбор интерфейса")

| Задача                                              | Интерфейс                                                        |
| --------------------------------------------------- | ---------------------------------------------------------------- |
| Просмотреть директорию или файл                     | Вкладка *Файлы* или REST API файлов                              |
| Немного изменить текст или Markdown                 | Вкладка *Файлы*                                                  |
| Передать сгенерированные или бинарные данные        | REST API файлов                                                  |
| Выполнить `git status`, `pull`, `commit` или `push` | *Терминал* или `/exec`                                           |
| Начать с готовой рабочей копии                      | `repo` при создании песочницы или сохраненный секрет типа `repo` |
| Хранить данные независимо от одной песочницы        | [Хранилище](/storage.md)                                         |

Файлы являются частью корневой файловой системы песочницы. Остановка и гибернация сохраняют эту файловую систему, удаление — нет. Хранилище аккаунта — отдельный сервис со своими правами доступа и жизненным циклом.

## Работа через веб-интерфейс[​](#work-in-the-web-ui "Прямая ссылка на Работа через веб-интерфейс")

Откройте активную песочницу и выберите *Файлы*. Дерево начинается с `/` и раскрывает рабочую директорию шаблона. С помощью панели инструментов или перетаскивания в директорию можно:

* загрузить один или несколько файлов;
* создать директорию;
* переименовать или переместить выбранный объект;
* рекурсивно удалить выбранную директорию или удалить файл;
* скачать выбранный файл;
* просмотреть изображения и Markdown, изучить код и отредактировать текстовые файлы.

Окно просмотра проверяет изменения на диске в фоне, но сохраняет показанную копию до нажатия *Перезагрузить*. Сохранение правки перезаписывает целевой файл. Бинарные файлы передаются как base64 и не открываются в текстовом редакторе.

Вкладка «Файлы» — привилегированный файловый браузер

Она показывает файловую систему песочницы, а не только директорию проекта. Права доступа Unix продолжают действовать. Не меняйте системные файлы без явной необходимости и не выводите файлы с учетными данными, например `~/.gitconfig`.

## Автоматизация файловых операций[​](#automate-file-operations "Прямая ссылка на Автоматизация файловых операций")

Всем эндпоинтам нужен ID песочницы и bearer-токен. Путь может быть абсолютным, относительным к домашней директории (`~/`) настроенного пользователя по умолчанию или относительным к рабочей директории по умолчанию.

| Операция                               | Запрос                                                 |
| -------------------------------------- | ------------------------------------------------------ |
| Прочитать файл                         | `GET /v1/sandboxes/{id}/files?path=...`                |
| Записать или заменить файл             | `POST /v1/sandboxes/{id}/files`                        |
| Загрузить multipart-файлы в директорию | `POST /v1/sandboxes/{id}/files/upload?path=...`        |
| Скачать сырые байты                    | `GET /v1/sandboxes/{id}/files/download?path=...`       |
| Получить содержимое директории         | `GET /v1/sandboxes/{id}/files/list?path=...&depth=...` |
| Получить свойства одного объекта       | `GET /v1/sandboxes/{id}/files/stat?path=...`           |
| Создать директории                     | `POST /v1/sandboxes/{id}/files/mkdir`                  |
| Переместить или переименовать          | `POST /v1/sandboxes/{id}/files/move`                   |
| Удалить файл или дерево директорий     | `DELETE /v1/sandboxes/{id}/files?path=...`             |

Запишите текстовый файл и прочитайте его:

```
curl --fail-with-body --silent --show-error \
  --request POST "$JUSTRUN_API/v1/sandboxes/$SANDBOX_ID/files" \
  --header "Authorization: Bearer $JUSTRUN_PAT" \
  --header "Content-Type: application/json" \
  --data '{
    "path": "~/workspace/config.json",
    "content": "{\"mode\":\"development\"}\n",
    "overwrite": true
  }'

curl --fail-with-body --silent --show-error \
  --get "$JUSTRUN_API/v1/sandboxes/$SANDBOX_ID/files" \
  --header "Authorization: Bearer $JUSTRUN_PAT" \
  --data-urlencode "path=~/workspace/config.json" |
  jq
```

Ответ чтения содержит `encoding: "utf-8"` для текста и `encoding: "base64"` для распознанного бинарного содержимого. При записи бинарных данных передайте base64-строку и укажите `"encoding": "base64"`.

Новые файлы создаются с правами `0644`, а недостающие родительские директории — автоматически. Укажите `overwrite: false`, если замена существующего файла должна завершаться ошибкой. Запись идет во временный соседний файл, который переименовывается после получения всего содержимого запроса; сервис не пишет через символическую ссылку и не заменяет ее.

Лимит тела HTTP-запроса настраивается в инсталляции и по умолчанию равен 20 МиБ. Внутренний файловый сервис может задавать дополнительный лимит загрузки. Превышение любого из них — `413 request.payload_too_large`, и это означает, что не записано ничего: незавершенная загрузка отменяется, прежнее содержимое файла остается нетронутым. Для больших долговечных артефактов используйте хранилище, а не файловую систему песочницы как объектное хранилище.

## Клонирование репозитория при создании[​](#clone-a-repository-at-creation "Прямая ссылка на Клонирование репозитория при создании")

Собственный API создания принимает один высокоуровневый объект `repo`:

```
{
  "template": "base",
  "repo": {
    "url": "https://github.com/acme/service.git",
    "ref": "main",
    "path": "~/service",
    "depth": 1,
    "required": true
  },
  "wait_until_ready": true
}
```

`url` должен использовать `https://` или `ssh://`. Необязательный путь назначения начинается с `~/`, не может содержать `..` и по умолчанию равен `~/<repository-name>`. `ref` превращается в `git clone --branch`, а `depth` включает клонирование с неполной историей.

Клонирование — шаг подготовки, а не часть загрузки VM. Песочница уже может показывать `running`, пока `provisioning.status` остается `in_progress`. `wait_until_ready: true` заставляет запрос создания ждать завершения подготовки; иначе опрашивайте песочницу до `ready` или `failed`.

По умолчанию клонирование считается обязательным. Его ошибка переводит песочницу в `failed`; у подготовки V1 нет действия повтора, поэтому исправьте причину и создайте песочницу заново. При `required: false` шаг клонирования может завершиться ошибкой, а песочница останется доступной.

## Аутентификация приватных репозиториев[​](#authenticate-private-repositories "Прямая ссылка на Аутентификация приватных репозиториев")

Не добавляйте токен в URL репозитория. Создайте секрет типа `git_credential` для HTTPS или секрет типа `ssh_key` для SSH URL, затем выберите секрет при создании песочницы. Сохраненный секрет типа `repo` может ссылаться по имени на соответствующий секрет `git_credential`.

Учетные данные HTTPS материализуются в помощник учетных данных Git, доступный только владельцу, внутри `~/.gitconfig` пользователя по умолчанию. SSH-ключи помещаются в `~/.ssh` этого пользователя. Клонирование запускается неинтерактивно от того же пользователя, поэтому отсутствующие учетные данные или неверный доступ приводят к ошибке, а не к зависшему запросу ввода.

После подготовки используется Git из выбранного шаблона:

```
curl --fail-with-body --silent --show-error \
  --request POST "$JUSTRUN_API/v1/sandboxes/$SANDBOX_ID/exec" \
  --header "Authorization: Bearer $JUSTRUN_PAT" \
  --header "Content-Type: application/json" \
  --data '{
    "cmd": "git",
    "args": ["-C", "/home/user/service", "status", "--short"]
  }' |
  jq '{exit_code, stdout, stderr}'
```

Отдельного REST API для команд `git status`, `pull`, `commit` или `push` нет. Используйте *Терминал*, если Git нужен интерактивный ввод, и `/exec` для детерминированной автоматизации. Считайте `push` внешним побочным эффектом и выдавайте учетным данным репозитория только необходимые права на рабочие процессы.

## Границы ошибок[​](#failure-boundaries "Прямая ссылка на Границы ошибок")

* Файловым операциям нужна активная среда выполнения. Сначала возобновите или разбудите песочницу.
* Ответы чтения буферизуют целый файл. Для крупных файлов используйте скачивание сырых байтов или хранилище.
* Удаление директории рекурсивно, а публичного API для отмены нет.
* Путь клонирования принадлежит пользователю по умолчанию. Git, запущенный от другого Unix-пользователя, может не увидеть те же учетные данные в домашней директории или из-за владельца файлов.
* Остановка сохраняет рабочее дерево, но завершает процессы Git; гибернация сохраняет память, однако удаленные сетевые соединения нужно устанавливать заново.
* Не выводите значения секретов, помощников учетных данных, приватных ключей или URL удаленных репозиториев с аутентификацией в логи и пакеты данных для поддержки.

## См. также[​](#related "Прямая ссылка на См. также")

* [Создание песочницы](/sandboxes/create-a-sandbox.md)
* [Команды, процессы и терминалы](/sandboxes/commands-processes-and-terminals.md)
* [Жизненный цикл песочницы](/sandboxes/lifecycle.md)
* [Секреты](/secrets.md)
* [Постоянные данные и хранилище](/sandboxes/persistence-and-storage.md)
* [Справочник REST API](/api-reference/rest.md)
* [Наблюдаемость и диагностика](/sandboxes/observability-and-troubleshooting.md)
