Конфиг и поиск репозиториев

Откуда CLI берёт список пакетов, и как добавлять в него репозитории без ручного редактирования JSON.

Несколько хостингов

Хостинг репозитория — GitHub или GitLab — никогда не задаётся вручную. Каждая команда, которой это нужно (bump, doctor, prs, release, list, tag), определяет его для каждого репозитория отдельно по git remote get-url origin, так что одна папка может свободно смешивать GitHub- и GitLab-репозитории — всё просто работает. gitlab.com распознаётся всегда; self-hosted GitLab-инстанс нужно один раз зарегистрировать по хосту — по одному только виду URL нельзя отличить «какой-то другой git-сервер» от «наш корпоративный GitLab», то же самое ограничение есть у gh/glab для GitHub Enterprise/self-hosted. Всё, что не распознано как GitLab, считается GitHub — так что для GitHub-only настройки вообще ничего не нужно.

Регистрация self-hosted-хоста — ещё один пункт через setup (ниже), либо вручную в gitlabHosts:

{
  "roots": ["C:\\work\\NPM"],
  "packages": [],
  "gitlabHosts": ["gitlab.company.com"]
}

pnpm workspaces

Корневая или пакетная папка, которая сама является pnpm-воркспейсом (есть pnpm-workspace.yaml, например layout вида packages/*), не требует отдельной записи в конфиге — она регистрируется точно так же, как любая другая папка в roots/packages, а любая команда, работающая с отдельными npm-пакетами, сама определяет воркспейс и разворачивает его в одну запись на каждого публикуемого участника — вместо package.json самого корня воркспейса (обычно приватного).

Определение читает список глобов packages: из pnpm-workspace.yaml — как блочную форму, которую сам pnpm и пишет (packages:\n - 'packages/*'), так и инлайновую форму массива (packages: [a, b]) — разрешает каждый паттерн относительно реальных директорий и оставляет только те, у которых есть собственный package.json. Ведущий ! исключает то, что совпало с более ранним паттерном — так же, как у самого pnpm. Папка, попавшая под паттерн, но без package.json (пустая заглушка, папка с документацией), молча пропускается — так же, как обычное сканирование root уже пропускает такие папки.

Это разворачивание применяется только к командам, работающим с отдельными npm-пакетами — list, outdated, audit, bump/publish/tag/release/sync-deps и exec — у каждой одна строка/чекбокс на участника воркспейса. Команды, работающие с самим физическим репозиторием — switch-default, clone, prs и большая часть doctor — по-прежнему работают один раз на репозиторий, потому что git checkout, синхронизация ветки или список pull/merge-запросов имеют смысл один раз на рабочее дерево, а не один раз на каждый живущий внутри пакет. Раздел «Cross-package dependencies» в doctor — единственное исключение: диапазон зависимости объявляется на уровне npm-пакета, так что именно эта проверка разворачивается до уровня пакетов, даже когда весь остальной doctor — нет.

Участник воркспейса никогда не путается с одноимённым пакетом где-то ещё в вашей папке, а два участника, забамленных до одного и того же номера версии, никогда не сталкиваются на одном git-теге или ветке — см. Релизы и публикация — там точная конвенция именования.

setup

Интерактивное меню для самого конфиг-файла. Показывает текущие списки roots, packages и gitlabHosts с пометками ✓ exists / ✗ not found (а для packages ещё и ! no package.json/.git here, если папка существует, но не является пакетом), и позволяет добавить директорию-root, директорию-package или GitLab-хост, отредактировать существующую запись или удалить её (с подтверждением).

polyrepo setup

Путь не проверяется строго — добавление ещё не существующего пути просто печатает предупреждение, на случай если папка появится позже (хост вообще не проверяется — на диске нечего искать). Изменения записываются на диск только при выборе «Save and exit»; «Discard changes and exit» отбрасывает всё сделанное за сессию.

Пример вывода — текущее состояние, прямо перед самим меню:

Configure package sources

Editing: C:\work\NPM\polyrepo.config.json

roots (subfolders are scanned as packages)
  1. C:\work\NPM  ✓ exists

packages (the folder itself is the package)
  (none)

gitlabHosts (self-hosted GitLab instances — gitlab.com always works)
  (none)

? What do you want to do?

Опции

--config <path>

Редактировать конфиг-файл, отличный от файла по умолчанию рядом с самим CLI.

Пример:

polyrepo setup --config "/path/to/polyrepo.config.json"

clone

Сверяет список репозиториев GitHub-организации (либо GitLab-группы) с тем, что уже склонировано под одной root-директорией, и клонирует недостающее.

polyrepo clone --org <name> [options]

1. gh repo list <org> (либо, с --provider gitlab, glab repo list --group <name>) — все репозитории под этой организацией/группой (архивные пропускаются по умолчанию).
2. Сравнивает имена с директориями, уже найденными под целевым root (--root, либо первая запись roots в конфиге, если не указано).
3. Показывает чекбокс недостающих (все отмечены по умолчанию), затем клонирует каждый выбранный git clone в целевой root, один за другим.

--org обязателен и не сохраняется в конфиге — roots/packages конфига описывают где локально лежат репозитории, а не с какого аккаунта они пришли. В отличие от всех остальных команд, clone не может определить хостинг по origin-удалённому репозиторию локального репозитория — репозитория ещё нет локально, — поэтому --provider явно говорит, что означает --org.

Пример вывода — два репозитория выбраны из чекбокса и клонируются по одному:

Clone missing repos from my-github-org (github)

Target root: C:\work\NPM

? Pick repos to clone into C:\work\NPM:
    vue-command-palette
    vue-toast-kit

[1/2] vue-command-palette
  $ git clone https://github.com/my-github-org/vue-command-palette.git C:\work\NPM\vue-command-palette
  ✓ Cloned into C:\work\NPM\vue-command-palette.

[2/2] vue-toast-kit
  $ git clone https://github.com/my-github-org/vue-toast-kit.git C:\work\NPM\vue-toast-kit
  ✓ Cloned into C:\work\NPM\vue-toast-kit.

Опции

--org <name>

GitHub-организация/пользователь либо GitLab-группа, чей список репозиториев нужно получить. Обязательный параметр.

--provider <github|gitlab>

К какому хостингу относится --org. По умолчанию github.

--root <path>

Root-директория для клонирования. По умолчанию — первая запись roots в конфиге.

--include-archived

Также предлагать архивные репозитории (по умолчанию пропускаются).

--packages <a,b,c>

Предложить только эти имена репозиториев, без интерактивного чекбокса.

--yes

Пропустить подтверждение «proceed?».

--dry-run

Напечатать, что было бы склонировано, без реального клонирования.

Пример:

polyrepo clone --org my-github-org --root "C:\work\NPM" --yes
polyrepo clone --org my-gitlab-group --provider gitlab --yes