Doctor

polyrepo doctor — проверка состояния из семи разделов, в основном read-only диагностика плюс несколько небольших, безопасных автофиксов.

polyrepo doctor [options]

Стоит запускать первым делом, если какая-то другая команда ведёт себя странно, в любой момент после переименования основной ветки на хостинге, или просто периодически, чтобы отловить накопившийся мусор до того, как его станет слишком много.

Репозитории обнаруживаются до того, как что-либо напечатано, так что раздел Environment ниже уже знает, какой хостинг(и) они реально используют — см. «Несколько хостингов» дальше.

Реальный вывод — запуск на папке репозиториев, где серьёзно ничего не сломано, только два случая, которые doctor и существует, чтобы ловить:

Environment

  ✓ Node.js v22.23.2 (>= 20 required).
  ✓ git version 2.49.0.windows.1.
  ✓ gh version 2.69.0 (2025-03-19) — authenticated as macrulezru.
  ! npm 10.9.8 — not authenticated (only needed for `polyrepo publish`). Run `npm login`.

Config

Config file: C:\work\NPM\polyrepo.config.json
Checking 18 package(s)...
  ✓ 18 package(s) discovered.

Remote sync

Checking 18 package(s) against their host, and pruning stale remote-tracking refs...
  ✓ 18 package(s) checked — local default-branch cache matches the host.
  ✓ os-detect: pruned 2 stale remote-tracking ref(s) (add-more-examples, new-documentation-refactor).

Branch sync

Fetching and comparing 18 package(s) against origin...
  ✓ 18 package(s) checked — all in sync with origin.

Branch protection

Checking 18 package(s) for branch protection...
  ✓ 18 package(s) checked — default branch is protected on all of them.

Stale bump branches

Checking 18 package(s) for leftover bump branches with a merged PR...
  ✓ No stale bump branches found.

Cross-package dependencies

  ✓ No stale local dependency references found.

Незалогиненный npm — это только предупреждение (он нужен лишь команде publish); две почищенные ветки на os-detect — это ссылки на PR, давно смёрдженные и удалённые на хостинге. Именно doctor их замечает и убирает — больше в CLI это не делает никто. Эта конкретная папка целиком на GitHub, поэтому в Environment показан только gh — см. ниже.

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

Хостинг (GitHub или GitLab) каждого найденного репозитория определяется заранее, по его origin-удалённому репозиторию — папка может свободно смешивать оба. Раздел Environment проверяет gh только если хотя бы один репозиторий на GitHub, и проверяет glab только если хотя бы один на GitLab — GitHub-only настройке никогда не предложат установить инструмент, который ей не нужен, и наоборот. Remote sync и Branch protection автоматически направляют каждый репозиторий к нужному хостингу; репозиторий, чей хостинг определить не удалось (нет origin-удалённого репозитория), отражается так же, как недостижимый хостинг — «не удалось проверить», а не как ошибка.

Разделы

1. Environment — версия Node.js (нужна 20+), есть ли git/npm в PATH и авторизован ли npm (только предупреждение, он нужен лишь для publish), плюс gh и/или glab — смотря что реально используют найденные репозитории — в PATH и авторизованы.

2. Config — сколько пакетов реально находит текущий конфиг, и какие репозитории грязные, находятся в состоянии detached HEAD, или не на своей основной ветке.

3. Remote sync — два смежных фикса, оба — обновление локального указателя, никогда не трогающее файл, ветку или коммит:

   • сравнивает закешированное локально имя основной ветки репозитория с тем, что реально сообщает его хостинг прямо сейчас. Git никогда не обновляет этот локальный кеш сам, так что переименование основной ветки на хостинге после клонирования иначе осталось бы незамеченным для всех остальных команд навсегда — там, где обнаружен дрейф, это чинится через git remote set-head origin --auto;
   • запускает git remote prune origin на каждом репозитории, убирая локальные ссылки remotes/origin/x, оставшиеся от веток, уже удалённых на хостинге.

   Оба пункта пропускаются для репозитория, чей хостинг не удалось достучаться (офлайн, gh/glab не авторизован, либо хостинг не распознан).

4. Branch sync — делает fetch и сравнивает локальную основную ветку каждого репозитория с origin/<default>: diverged (одновременно и опережает, и отстаёт — fast-forward не сработает, нужно решать руками), behind only (можно безопасно подтянуть через switch-default), либо ahead only (есть локальные коммиты, ещё не запушенные).

5. Branch protection — реально ли включена защита основной ветки на её собственном хостинге у каждого репозитория прямо сейчас. Только отчёт — включение защиты это осознанное решение о политике, не то, что имеет смысл настраивать без спроса.

6. Stale bump branches — bump мёрджит через PR/MR, намеренно оставляя ветку на origin, так что каждый завершённый bump навсегда оставляет и локальную копию ветки тоже. Этот раздел показывает, сколько локальных веток совпадают с шаблоном <version>-version-bump и у них уже есть смёрдженный PR/MR. См. --clean-branches ниже.

7. Cross-package dependencies — не устарел ли у какого-то локального пакета диапазон dependencies/devDependencies/peerDependencies, указывающий на другой локальный пакет.

Опции

--clean-branches

Превращает раздел 6 в интерактивный чекбокс — выбираете, какие устаревшие локальные bump-ветки удалить. Использует git branch -d, который откажется, а не удалит принудительно, если ветка вдруг не до конца смёрджена локально. Ветка на origin никогда не трогается — её удаление не входит в задачу этой команды, это более чувствительное общее состояние, чем локальная ветка, которую никто больше не видит.

Пример:

polyrepo doctor --clean-branches