core.git

soul-sidesoulstack.scmscm

Клонирование и обновление git-репозитория на хосте через системный git.

core.git вызывает системный git как подпроцесс (clone / pull --ff-only / rev-parse); собственного git-клиента модуль не содержит. Идемпотентность — по наличию path/.git: cloned клонирует только при отсутствии, pulled дополнительно подтягивает remote и рапортует changed лишь при сдвиге HEAD. clone/pull исполняют код из репозитория (хуки, transport), поэтому repo обязан указывать на доверенный источник. MVP сознательно не покрывает смену remote URL, submodule, lfs и sparse-checkout.

Требования

Rootне требуется
Сторонаsoul-side
Коллекцияsoulstack.scm
Категорияscm

Capabilitiesexec_subprocessnetwork_outbound

core.git.cloned — По пути path лежит git-репо (клонируется при отсутствии).

Меняется, когда

path/.git отсутствовал и репозиторий склонирован.

Не меняется, когда

path/.git уже есть — содержимое не трогается, новый pull не выполняется.

Параметры

Параметр	Тип	Обяз. / дефолт	Описание
`repo`	`string`	required	URL репозитория.
`path`	`string`	required	Целевой каталог клона.
`branch`	`string`	optional	Ветка (default main).
`depth`	`int`	optional	Глубина shallow-клона (--depth).

Пример — Выложить репозиторий на хост (shallow-клон)

- name: Clone deploy repo
  module: core.git.cloned
  params:
    repo: https://github.com/example/deploy.git
    path: /opt/deploy
    branch: main
    depth: 1

Output

Поле	Тип	Описание
`path`	`string`
`cloned`	`true`
`head`	`string (текущий HEAD, sha, best-effort)`

core.git.pulled — По пути path лежит git-репо, подтянутый до remote через git pull --ff-only.

Меняется, когда

path/.git отсутствует — выполняется clone. Репозиторий на месте — меняется только когда HEAD сдвинулся (сверка rev-parse HEAD до и после).

Не меняется, когда

Репозиторий на месте и HEAD не сдвинулся.

Параметры

Параметр	Тип	Обяз. / дефолт	Описание
`repo`	`string`	required	URL репозитория.
`path`	`string`	required	Целевой каталог клона.
`branch`	`string`	optional	Ветка (default main).
`depth`	`int`	optional	Глубина shallow-клона (--depth).

Пример — Держать рабочую копию синхронной; register — чтобы рестартить сервис при сдвиге HEAD

- name: Keep deploy repo up to date
  module: core.git.pulled
  register: deploy_repo
  params:
    repo: https://github.com/example/deploy.git
    path: /opt/deploy
    branch: main

Output

Поле	Тип	Описание
`path`	`string`
`cloned`	`true`
`head`	`string (текущий HEAD, sha, best-effort)`

Заметки

Требует исходящей сети (network_outbound): clone/pull ходят на remote repo.
pull — только fast-forward (--ff-only): расходящаяся локальная история не мёржится силой, шаг падает — защита от тихой потери локальных коммитов на хосте.
Аутентификация и transport (ssh-agent, credential helper, ~/.netrc) — на стороне системного git; модуль их не настраивает.
head в output — best-effort: если rev-parse не отдал sha, поле пустое (на основной flow это не влияет).

Безопасность и умолчания

clone/pull исполняют код из репозитория — главный риск модуля: git при checkout прогоняет хуки репо (.git/hooks/*: post-checkout, post-merge), а transport-параметры могут запустить произвольную команду. Модуль не отключает хуки и не песочит git.
repo обязан указывать на доверенный источник: клонирование недоверенного репозитория = исполнение кода его автора с привилегиями процесса soul; на практике для системных путей агент под root, тогда хуки исполнятся под root — цена доверия к repo только растёт.
Argument-injection guard -- прикрывает repo/path (репо, начинающийся с -, не распарсится git как опция), но branch подставляется до -- и без валидации — держите branch под контролем автора Destiny, как и repo.

core.git

Требования

Состояния

Заметки

Безопасность и умолчания

См. также