doc: Updated templateignore details

content/documentation/admin/actions/types.ru.md

@@ -708,22 +708,270 @@ createContent: false
 
 Для исключения подобных файлов из механизма рендеринга следует добавить в корень репозитория файл `.templateignore` с соответствующим содержимым.
 
-Пример файла `.templateignore` для игнорирования содержимого директорий `helm`, `docs`:
+В **каждой строке** `.templateignore` задаётся одно правило — путь или маска. Если в строке есть `{{`, **вся строка** выполняется как один шаблон Go с теми же переменными и функциями, что при подстановке в **имена** файлов и каталогов (подробнее — [«Как обрабатывается строка правила»](#templateignore-templates)). Если `{{` в строке **нет**, подстановка переменных из `values.yaml` и из запроса действия **не делается**: строка читается как есть и сравнивается с относительным путём на диске, допускаются литералы и символы маски `*` и `**`.
+
+Пример файла `.templateignore` **только с масками** пути, без шаблонов подстановки, для игнорирования содержимого директорий `helm`, `docs`:
 
 ```sh
 helm/**
 docs/**
 ```
 
-Файл `.templateignore` является опциональным.
+#### Добавление путей в игнор
+
+1. В корне шаблонного репозитория создайте или отредактируйте файл `.templateignore` (по одному правилу на строку).
+
+1. Каждая строка — это **одно** правило: путь от **корня** репозитория. В нём допускаются обычные символы пути и **маски**: звёздочка `*` в имени сегмента, последовательность `**` — для произвольной глубины вложенных каталогов. Платформа сопоставляет относительный путь с маской по встроенным правилам (аналогично распространённым соглашениям для масок в файлах игнорирования в системах контроля версий).
+
+1. Чтобы подставить фрагмент пути из `values.yaml` или из поля **values** запроса действия, используйте в строке конструкции **Go template** (`{{ ... }}`). Если в строке есть `{{`, платформа обрабатывает **всю строку от начала до конца** как **один** шаблон Go: нельзя оставить часть строки «простым текстом» и шаблонизировать только середину пути. Примеры — в разделе [«Примеры Go template в `.templateignore`»](#templateignore-go-examples).
+
+1. Пустые строки и строки, начинающиеся с `#`, при разборе файла пропускаются — их можно использовать для комментариев.
+
+#### Примеры без подстановки (только маски пути)
+
+Отдельные файлы в корне:
+
+```sh
+package-lock.json
+yarn.lock
+LICENSE
+.env.local
+```
+
+Каталоги целиком и типичные артефакты сборки:
+
+```sh
+vendor/**
+node_modules/**
+dist/**
+build/tmp/**
+```
+
+Вложенность по маске:
+
+```sh
+docs/**/*.pdf
+charts/*/values.schema.json
+.github/workflows/**
+```
+
+Секреты по расширению во всём дереве:
+
+```sh
+**/*.pem
+**/*.key
+```
 
 <a id="templateignore-templates"></a>
 
-**Шаблоны в правилах исключения.** Строки в `.templateignore` и в файлах, перечисленных в поле **additionalIgnoreFiles**, могут содержать выражения в формате Go template. Подстановка выполняется теми же переменными, что объединены из `values.yaml` и из поля **values** в запросе действия.
+#### Как обрабатывается строка правила
+
+Переменные для раскрытия правил те же, что объединены из `values.yaml` в корне шаблонного репозитория и из поля **values** в запросе действия (приоритет у **values** в запросе).
+
+Для **каждой** непустой строки из `.templateignore` или из файла из **additionalIgnoreFiles** платформа делает следующее.
+
+1. В список правил **всегда** попадает строка **как в файле**, без изменений. Именно её потом сравнивают с путём к файлу в первую очередь — это нужно, когда в именах на диске ещё есть фрагменты вроде `{{ .module }}` до переименования.
+
+1. Если в строке есть `{{`, платформа **один раз** прогоняет **всю** строку через шаблонизатор [Go template](https://developer.hashicorp.com/nomad/docs/reference/go-template-syntax) с теми же возможностями, что при подстановке в **имена** файлов и каталогов (встроенные функции платформы и набор **Sprig**). Если `{{` в строке нет, этот шаг пропускают.
+
+1. Если шаг подстановки был и полученный текст **отличается** от строки в файле (включая случай «на выходе пусто»), в список правил **добавляют вторую запись** — уже с этим полученным текстом. Итого из одной строки файла может получиться **две** записи в списке. При проверке пути к файлу смотрят **обе**: достаточно совпадения с **любой** из них — файл попадает под правило.
+
+Дальше при обходе дерева для каждого пути к файлу вычисляется путь **относительно корня** клонированной копии (с прямыми слешами). Путь сравнивается с каждым правилом: сначала по правилам сопоставления с маской (в том числе с использованием `*` и `**`), при необходимости — по **точному** совпадению строки правила и относительного пути.
 
-Для каждой строки учитываются и исходный текст, и результат подстановки: так правила применимы и к путям до переименования каталогов и файлов (когда в именах ещё есть фрагменты шаблона), и после него.
+Так одна строка в файле может задать **два** правила: например, исходное `charts/{{ .name }}/**` (чтобы не трогать путь до переименования каталогов), и раскрытое `charts/billing/**` (чтобы совпадало с путём после подстановки переменных в имена на диске). Поэтому правила работают и «до», и «после» этапа переименования каталогов по шаблону.
 
-Файлы из **additionalIgnoreFiles** задают пути, которые удаляются из рабочей копии; файл `.templateignore` задаёт пути, которые не переименовываются и не обрабатываются как шаблоны содержимого.
+Если шаблон в строке синтаксически неверен или обращается к отсутствующему полю, раскрытие правил завершается **ошибкой**, и рендер репозитория не продолжается.
+
+Поле **additionalIgnoreFiles** в действии задаёт **имена дополнительных файлов** в корне репозитория; в каждом из них — такие же строки-правила, как в `.templateignore`, с тем же раскрытием шаблонов. Но смысл другой: совпавшие пути **убирают из рабочей копии** (каталог или файл удаляют), и делают это **дважды** — в начале и в конце цепочки обработки, чтобы эти объекты не участвовали в дальнейших шагах и не попали в итоговый репозиторий.
+
+Файл **`.templateignore`** наоборот означает «**не шаблонизировать**»: для совпавших путей платформа **не подставляет** переменные в **содержимое** файлов и **не применяет** к соответствующим каталогам переименование по шаблону в пути. Сами файлы и каталоги при этом **не удаляются** только из‑за записи в `.templateignore` — они остаются в копии, но обрабатываются как обычный текст и обычные имена, без шага шаблонизации.
+
+<a id="templateignore-go-examples"></a>
+
+#### Примеры Go template в `.templateignore`
+
+Ниже в каждом примере показаны фрагменты `values.yaml` (или эквивалентные поля в **values** запроса) и строки **`.templateignore`**. Несколько независимых правил задают **несколькими строками** файла: результат одной строки-шаблона — одна строка с маской; перевод строк внутри результата шаблона **не** делит правило на несколько.
+
+Имя каталога в правиле берётся из `values.yaml` или из **values** действия:
+
+`values.yaml`:
+
+```yaml
+project: payment-gateway
+```
+
+`.templateignore`:
+
+```go
+{{ .project }}/legacy/**
+```
+
+В набор правил попадут строки `{{ .project }}/legacy/**` и `payment-gateway/legacy/**`.
+
+Сегмент пути из переменной и статический хвост:
+
+`values.yaml`:
+
+```yaml
+lang: ru
+```
+
+`.templateignore`:
+
+```go
+apps/{{ .lang }}/messages.yaml
+```
+
+Условное правило **в одной строке** (при `skipGenerated: false` подстановка даёт пустую строку — она всё равно добавляется вторым правилом; исходная строка с `{{` как маска пути обычно не совпадает с путями. При `skipGenerated: true` вторым правилом становится `generated/**`):
+
+`values.yaml`:
+
+```yaml
+skipGenerated: false
+```
+
+`.templateignore`:
+
+```go
+{{- if .skipGenerated }}generated/**{{- end }}
+```
+
+Вариант «игнорировать только не production»:
+
+`values.yaml`:
+
+```yaml
+tier: staging
+```
+
+`.templateignore`:
+
+```go
+{{- if ne .tier "prod" }}mock/**{{- end }}
+```
+
+Использование `printf` для сборки строки маски (удобно, если имя чарта в переменной):
+
+`values.yaml`:
+
+```yaml
+chartName: wordpress
+```
+
+`.templateignore`:
+
+```go
+{{ printf "charts/%s/**" .chartName }}
+```
+
+Значение по умолчанию для «пустого» значения — функция **`default`** из набора **Sprig**. Поле в данных должно существовать (иначе при раскрытии сработает `missingkey=error`); для «не задано в YAML» заведите ключ с пустой строкой или используйте условие `if` / `index`:
+
+`values.yaml`:
+
+```yaml
+envName: ""
+```
+
+`.templateignore`:
+
+```go
+{{ default "dev" .envName }}/secrets/**
+```
+
+При пустом `envName` в правило попадёт и `{{ default "dev" .envName }}/secrets/**`, и `dev/secrets/**`.
+
+Опциональный сегмент пути ([`with`](https://pkg.go.dev/text/template#hdr-Actions)):
+
+`values.yaml`:
+
+```yaml
+analyticsModule: tracking
+```
+
+`.templateignore`:
+
+```go
+{{ with .analyticsModule }}{{ . }}/vendor/**{{ end }}
+```
+
+Если `analyticsModule` пусто, шаблон даёт пустую строку (см. правила раскрытия выше).
+
+Доступ к полю вложенной структуры по строковому ключу [`index`](https://pkg.go.dev/text/template#hdr-Functions):
+
+`values.yaml`:
+
+```yaml
+regions:
+  primary: eu-west
+```
+
+`.templateignore`:
+
+```go
+configs/{{ index .regions "primary" }}/bootstrap.yaml
+```
+
+Удаление пробелов в сегменте имени — функция **`trim`** из набора **Sprig**:
+
+`values.yaml`:
+
+```yaml
+serviceName: " billing-api "
+```
+
+`.templateignore`:
+
+```go
+{{ trim .serviceName " " }}/logs/**
+```
+
+Несколько фрагментов в одной маске:
+
+`values.yaml`:
+
+```yaml
+base: services
+variant: canary
+```
+
+`.templateignore`:
+
+```go
+{{ .base }}/{{ .variant }}/**/*.tmp
+```
+
+#### Примеры для `additionalIgnoreFiles`
+
+В спецификации действия перечисляются **имена файлов** в корне репозитория (например, `.ship-ignore`, `.ci-remove`). Формат строк внутри таких файлов тот же: комментарии `#`, пустые строки, маски пути, при необходимости — шаблоны Go в строках.
+
+Файл `.ship-ignore` в шаблоне:
+
+```sh
+# не попадает в целевой репозиторий
+local/fixtures/**
+scratchpad.md
+```
+
+Фрагмент запроса действия:
+
+```yaml
+additionalIgnoreFiles:
+  - .ship-ignore
+```
+
+Шаблон в файле для **additionalIgnoreFiles** (удаление каталога, имя из переменных):
+
+Файл `.env-drop` в корне шаблона:
+
+```go
+{{ .obsoleteDir }}/**
+```
+
+При `obsoleteDir: legacy-ui` из **values** после раскрытия в списке удаления окажутся и `{{ .obsoleteDir }}/**`, и `legacy-ui/**` — совпавшие пути будут удалены из копии перед финальными шагами.
+
+{{< alert level="info" >}}
+Не путайте назначение: **`.templateignore`** оставляет файлы на диске, но отключает для них переименование пути и рендер содержимого; списки из **additionalIgnoreFiles** **удаляют** совпавшие пути из рабочей копии.
+{{< /alert >}}
 
 ### Пример структуры директорий шаблонного репозитория
 
@@ -749,6 +997,8 @@ docs/**
 └── .templateignore
 ```
 
+<a id="локальная-отладка"></a>
+
 ### Локальная отладка
 
 Для локальной отладки шаблонов доступна утилита **ddp-render-dir**.