Ten sam plik YAML dla ESPHome mógł dawać inną konfigurację w zależności od komputera, na którym go skompilowano. Zmiana #21678 autorstwa Jonathana Swobody, scalona z gałęzią rozwojową 26 października 2026, usuwa ten problem dla znaczników !include_dir_*: pliki są teraz wczytywane według nazw. Poprawka ma trafić do ESPHome 2026.11, chyba że wcześniej zostanie przeniesiona do któregoś z wydań poprawkowych 2026.10.x.

Skąd brał się problem

Funkcja, która zbiera pliki dla !include_dir_named, !include_dir_list, !include_dir_merge_list i !include_dir_merge_named, zwracała je w takiej kolejności, w jakiej podał je system plików. Na Linuksie z ext4 to kolejność wynikająca z funkcji skrótu, na Windowsie z NTFS - alfabetyczna. Nic tego nie sortowało, a kolejność ma znaczenie w kilku miejscach:

  • przy !include_dir_merge_named, gdy dwa pliki ustawiają ten sam klucz, wygrywa plik wczytany jako ostatni;
  • przy packages: !include_dir_named packages/ pakiety wczytane później nadpisują wcześniejsze, więc to, który pakiet wygrywał przy sprzecznych opcjach, zależało od kolejności plików;
  • w wariantach z listami od kolejności plików zależy kolejność elementów listy, na przykład kolejność tworzenia encji;
  • skrót konfiguracji i wygenerowany kod mogły się różnić między komputerami przy tym samym YAML-u.

Konfiguracja zbudowana w dodatku ESPHome w Home Assistant i ta sama konfiguracja skompilowana na laptopie z Windowsem mogły więc dostać różne wartości tej samej opcji, bez żadnego ostrzeżenia.

Co się zmienia

ESPHome sortuje teraz katalogi i pliki według nazw. Najpierw idą pliki z danego katalogu w kolejności nazw, potem każdy podkatalog, również według nazwy. Zasada „wygrywa późniejszy plik” oznacza więc teraz plik późniejszy w kolejności nazw, na każdym komputerze.

Jeden przypadek, który dotąd przechodził po cichu, teraz kończy się błędem. !include_dir_named przeszukuje też podkatalogi, ale klucz tworzy wyłącznie z nazwy pliku. Pliki dir/a.yaml i dir/sub/a.yaml dostawały więc ten sam klucz a, a jeden z nich po cichu znikał. Teraz ESPHome zatrzymuje się z komunikatem, który wymienia oba pliki:

!include_dir_named: dir/a.yaml and dir/sub/a.yaml both use the key 'a'; rename one of them

Konfiguracja z dwoma plikami o tej samej nazwie w jednym katalogu dla !include_dir_named wcześniej się wczytywała, tyle że bez jednego z nich. Teraz zgłasza ten błąd, a naprawa polega na zmianie nazwy jednego z plików. Autor zaznacza, że nie dotyczy to żadnej konfiguracji w repozytorium ESPHome.

Kto powinien sprawdzić konfigurację

Każdy, kto dzieli konfiguracje urządzeń na katalogi, zwłaszcza wspólne pakiety dołączane przez !include_dir_named. Jeśli dwa pliki w takim układzie ustawiają tę samą opcję, o zwycięzcy decydują teraz nazwy plików. Numery na początku nazw, na przykład 10-base.yaml i 20-overrides.yaml, jasno określają zamierzoną kolejność.