Глобальные флаги
Флаги, доступные в каждой подкоманде aggrega.
--workspace-root <path>
Использовать <path> как корень рабочего пространства, полностью пропуская обнаружение. Если флаг не указан, aggrega находит корень, поднимаясь вверх от текущего каталога, — а если этот обход ничего не находит и команда указывает свою сущность Release или документ по абсолютному пути, то поднимаясь вверх от папки этого файла; о том, что задаёт корень, в каком порядке и какие команды указывают такой файл, см. Конфигурация.
AGGREGA_WORKSPACE_ROOT — аналог флага в виде переменной окружения: если --workspace-root не задан, корень задаёт эта переменная. Если флаг задан, приоритет у него.
Корень остаётся корнем, где бы он ни был задан, включая серверы: запрос к aggrega mcp, не указывающий собственного рабочего пространства, обрабатывается в нём, а выше него ничего не ищется. Корень, который не является существующей папкой, — путь, не указывающий ни на что или указывающий на файл, — отклоняется каждой командой, читающей своё рабочее пространство, прежде чем команда сделает что-либо ещё; aggrega serve и слушатель aggrega mcp отказываются запускаться с таким корнем, а aggrega mcp через стандартные ввод и вывод всё равно запускается и отвечает отказом на каждый вызов, действующий в этом рабочем пространстве. В отказе указывается, что из двух его задало, --workspace-root или AGGREGA_WORKSPACE_ROOT, и значение в точности в том виде, в каком оно было задано. Команда, не читающая рабочее пространство, например aggrega version, не читает и корень и из-за него не отклоняется.
Если не задано ни то, ни другое и обнаружение ничего не находит, корнем становится папка, в которой запущена команда, и команда, читающая своё рабочее пространство, сообщает об этом одной строкой в стандартный поток ошибок, указывая эту папку и этот флаг; см. Конфигурация, где также объясняется, почему в такой папке ничего не записывается в кэш артефактов.
Глобальный файл конфигурации
--config <path> явно задаёт глобальный файл конфигурации для одного вызова. Он имеет приоритет над переменной окружения AGGREGA_CONFIG, которая, в свою очередь, имеет приоритет над расположением по умолчанию, — и поскольку оба способа указывают файл намеренно, несуществующий путь приводит к явной ошибке, а не к молчаливому откату. В отличие от переменных настроек AGGREGA_*, ни один из них не переопределяет отдельную настройку: они выбирают, какой файл применяется. Какой бы файл ни был выбран, собственные файлы конфигурации проекта по-прежнему накладываются поверх него. Порядок разрешения и то, что должно находиться в этом файле, описаны в разделе Конфигурация.
--config и переменная окружения AGGREGA_CONFIG выбирают не только источник чтения, но и цель записи: команда, запущенная с --config <path>, читает конфигурацию из этого файла и применяет своё изменение к тому же файлу, поэтому то, что записывает команда, читает обратно следующая команда, вызванная в той же форме.
Команды, изменяющие конфигурацию, выбирают файл для записи по характеру настройки: конфигурация инструмента на уровне машины (реестр) по умолчанию записывается в глобальный файл, а конфигурация, участвующая в сборке (привязка провайдера или подключение к сокету governance/linter/importer), по умолчанию записывается в зафиксированный файл проекта. Чтобы переопределить это, передайте --global или --workspace; команда выведет, куда она выполнила запись.
Чтобы подготовить глобальную конфигурацию на новой машине — зарегистрировать реестр и его политику доверия подписям, чтобы подписанные артефакты загружались и проверялись без ручного редактирования YAML, — выполните aggrega config init. Чтобы увидеть, что применяется прямо сейчас, а с --origin — какой слой определил каждую настройку, выполните aggrega config show.
--offline
Запрещает любые обращения к сети на время этого запуска.
Автономный режим — это состояние рабочего пространства, а не режим отдельной команды, и его можно задать в трёх местах: этим флагом, переменной AGGREGA_OFFLINE и ключом верхнего уровня offline в файле конфигурации. Все три означают одно и то же и действуют в обычном порядке: флаг важнее переменной, а переменная важнее файла.
Выключение режима — такая же задача флага, как и его включение. --offline=false разрешает сеть для одной команды там, где режим включён зафиксированным в репозитории файлом конфигурации или экспортированной переменной. Это важно, когда файл не вам редактировать: проект, чей .aggrega-config.yaml содержит offline: true, запрещает публикацию всем, кто его клонирует, и передача --offline=false — единственное решение, не требующее ни коммита, ни экспортированной переменной.
Что запрещается, а что нет
Граница определяется тем, что нужно для работы, а не тем, какая команда была введена.
Запрещается, потому что не может быть верным без обращения к реестру:
--upgrade, где бы он ни встречался. Он заново разрешает каждую зависимость и поднимает каждую до наивысшей версии, которую реестр предлагает в данный момент, а «наивысшая доступная» — это утверждение о том, что реестр отдаёт прямо сейчас. Запуск с заполненным кешем закрепил бы то, что случайно оказалось в кеше, сообщая при этом, что версии подняты до новейших, а это хуже остановки.- Команды, сама работа которых — обмен данными по сети:
aggrega push,aggrega push-artifactиaggrega registry update. Они сообщают об этом до чтения вашей сущности или обхода ваших репозиториев, а в отказе указано, какое из трёх мест включило режим, чтобы тот, кто не вводил флаг, знал, где искать.
Не запрещается, потому что машина, возможно, уже может это выполнить:
- Обычный
aggrega pullиaggrega build --auto-pull. Оба соблюдают уже записанные закрепления и разрешают только то, что их не имеет, поэтому рабочее пространство, все ссылки которого есть в кеше или в каталогеcatalog_dirs, завершает работу вообще без обращения к сети. Если такому запуску действительно нужно что-то загрузить, он получает отказ в этот момент с указанием ссылки, которую не удалось удовлетворить. aggrega buildс заполненным lock-файлом, который читает всё своё замыкание из кеша. Единственное обращение к сети у него — восстановление: если копия закреплённого внешнего входа пропала из хранилища, этот вход загружается заново по дайджесту, уже записанному в lock-файле. В автономном режиме нет транспорта даже для этого, поэтому отсутствующая копия вместо этого останавливает сборку с указанием на режим.- Публикация с
--dry-run. Всё её поведение сводится к тому, чтобы сообщить, что было бы опубликовано, ничего не вызывая, поэтому это безопасная для автономного режима форма публикации, а не противоречие ему.
Изолированная от сети машина с локальной копией своего каталога и артефактов — именно тот случай, ради работоспособности которого существует это разделение: такое рабочее пространство находится в автономном режиме, и почти всё, что оно делает, по-прежнему выполнимо.
Приоритет конфигурации
Флаг имеет приоритет над всем остальным: над переменной окружения, над файлами конфигурации и над встроенным значением по умолчанию. Полная иерархия описана в разделе Конфигурация, а список переменных с префиксом AGGREGA_ — в environment-variables.md.
aggrega config show --origin сообщает, какой из этих уровней определил каждую настройку, а введённый вами флаг указывается как флаг — поэтому, если отказ называет уровень, которого вы не ожидали, проверить это можно с помощью этой команды.
См. также
- configuration.md — в каком файле должен находиться параметр, и полная модель приоритетов.
- environment-variables.md — полный справочник переменных
AGGREGA_*. - aggrega-serve.md — демон определяет своё рабочее пространство тем же способом обнаружения корня.
| Флаг | По умолчанию | Описание |
|---|---|---|
--config | — | путь к глобальному файлу конфигурации; переопределяет переменную окружения AGGREGA_CONFIG и расположение по умолчанию. Файлы конфигурации из дерева рабочего пространства по-прежнему накладываются поверх |
--no-color | false | Отключить цвета ANSI во всём выводе. Также учитывается переменная окружения NO_COLOR |
--offline | false | Отказывать в любом обращении к сети в рамках этого запуска: автономный режим, включаемый без правки конфигурации. Передайте —offline=false, чтобы отключить его на один запуск, если файл конфигурации или AGGREGA_OFFLINE уже его включает. Отказ получает то, что невозможно без реестра: —upgrade, чья единственная задача — поднять каждую зависимость до наивысшей версии, которую реестр предлагает в данный момент, и команды, сама работа которых — сетевой обмен: push, push-artifact и registry update. По-прежнему выполняется всё, что машина уже может обеспечить: сборка по заполненному lock-файлу, —auto-pull для ссылок, уже находящихся в кэше или в локальном каталоге, и пробный запуск, который сообщает, что он опубликовал бы, и ничего не вызывает |
--plain | false | Режим доступности: отключить цвета и выводить простые статичные строки прогресса без анимации спиннера и перерисовки курсора, даже в терминале. Предназначен для программ чтения с экрана |
--workspace-root | — | абсолютный путь, используемый как корень рабочего пространства (обнаружение пропускается) |