Projekt Power BI (.pbip) w Git - które pliki zapisać, a które pominąć

Power BI - Potoki wdrażania, Fabric, Copilot i telefon

Projekt Power BI (.pbip) w Git - które pliki zapisać, a które pominąć

W skrócie

Ponad sto plików na liście zmian, a wśród nich binarny plik z danymi: to pokazuje Git przy pierwszym zatwierdzeniu projektu Power BI (.pbip), zapisanego po to, żeby trzymać raport w repozytorium. Na modelu Nordvelli z kursu rozkładamy projekt na części: które pliki są definicją raportu i modelu, które są lokalne i jak przed pierwszym zatwierdzeniem sprawdzić, że dane zostają poza repozytorium.

Jak to wygląda w praktyce

Po poleceniu git add . w folderze projektu git status pokazuje na liście plików do zatwierdzenia ścieżkę nordvella_26_pipeline.SemanticModel/.pbi/cache.abf, a obok niej pliki localSettings.json z folderów .pbi. Samo git status przed dodaniem plików tego nie zdradzi, bo nieśledzony folder pokazuje jedną linią. W projekcie z kursu plik cache.abf miał 6,9 MB, a pozostałe pliki projektu, 160 plików tekstowych, razem 471 216 bajtów. Git nie pokaże różnic w pliku binarnym, a razem z nim do repozytorium trafiają dane firmy z ostatniej edycji modelu.

Drugi objaw to zmiany, których nikt nie robił. Plik localSettings.json w folderach .pbi przechowuje ustawienia jednej osoby na jednym komputerze, więc po pracy kolegi może się pojawiać jako zmieniony albo w konflikcie. Trzeci to cały plik TMDL oznaczony jako zmieniony po drobnej poprawce, gdy Git na innym komputerze inaczej traktuje końce linii. Odwrotna sytuacja nie jest błędem: projekt sklonowany bez cache.abf otwiera się w Power BI Desktop bez danych.

Dlaczego tak się dzieje

Projekt Power BI to folder z dwoma elementami: nazwa.Report z definicją raportu w plikach JSON i nazwa.SemanticModel z definicją modelu w plikach TMDL. TMDL (ang. Tabular Model Definition Language) to tekstowy zapis modelu, w którym każda tabela, rola i kultura ma osobny plik. Obok definicji Desktop zapisuje pliki lokalne. Według dokumentacji Microsoft localSettings.json zawiera ustawienia tylko dla bieżącego użytkownika i komputera, a cache.abf to kopia zapasowa Analysis Services z modelem i danymi z ostatniej edycji. Oba pliki powinny być wykluczone z kontroli wersji.

Desktop dopisuje te wykluczenia do pliku .gitignore przy zapisie projektu, ale dokumentacja Microsoft zastrzega, że tworzy go tylko wtedy, gdy w wybranym folderze ani w nadrzędnym repozytorium Git nie ma już pliku .gitignore. Gdy zapisujesz projekt do podfolderu istniejącego repozytorium z własnym .gitignore, Desktop nowego pliku nie tworzy. Jeśli tamten plik nie ma reguł dla Power BI, polecenie git add . dodaje także cache.abf z danymi. Osobna sprawa to unappliedChanges.json: według dokumentacji trafia do Git domyślnie i przechowuje zmiany zapytań Power Query zostawione na później.

Zobacz też: Szkolenie Power BI - Desktop, DAX i Online + Copilot

Co zrobić krok po kroku

1. W Power BI Desktop wybierz Plik, Zapisz jako, kliknij Przeglądaj to urządzenie i w polu typu pliku wybierz Pliki projektów usługi Power BI (*.pbip). Wskaż pusty folder z krótką ścieżką, u nas C:\pbi\l26\projekt. Według dokumentacji Microsoft ścieżka plików projektu ma w Windows domyślny limit 260 znaków, a długie nazwy tabel szybko go wyczerpują.
2. Otwórz plik .gitignore w folderze projektu. W projekcie z kursu Desktop zapisał w nim dokładnie dwie reguły, widoczne niżej. Gdy pliku nie ma, bo repozytorium ma .gitignore wyżej w drzewie folderów, dopisz te dwie linie do istniejącego pliku.

   **/.pbi/localSettings.json
   **/.pbi/cache.abf

3. Przed pierwszym zatwierdzeniem sprawdź, czy Git pomija plik z danymi. Polecenie git check-ignore -v wypisuje regułę, która wyklucza plik, u nas .gitignore:2:**/.pbi/cache.abf i ścieżkę pliku. Polecenie git status -u, czyli lista z każdym nieśledzonym plikiem osobno, nie może już pokazywać ścieżki do cache.abf. Gdy check-ignore nic nie wypisuje mimo reguły w .gitignore, plik jest już śledzony: sama reguła go nie usunie i trzeba go wycofać z indeksu poleceniem git rm --cached.

   git check-ignore -v nordvella_26_pipeline.SemanticModel/.pbi/cache.abf
   git status -u
   git rm --cached nordvella_26_pipeline.SemanticModel/.pbi/cache.abf

4. Zatwierdź pliki definicji. W projekcie Nordvelli to plik nordvella_26_pipeline.pbip, w folderze raportu definition.pbir, folder definition ze stronami i wizualizacjami, StaticResources z motywem i plik .platform. W folderze modelu: definition.pbism, diagramLayout.json, .platform, .pbi/editorSettings.json, zapytania z folderu DAXQueries i pliki TMDL: database.tmdl, model.tmdl, expressions.tmdl z parametrem i zapytaniami, relationships.tmdl, cultures/pl-PL.tmdl, 19 plików tabel i 6 plików ról. Ustawienia edytora według dokumentacji są wspólne dla wszystkich użytkowników, więc zostają w repozytorium.
5. Ustaw końce linii. Według dokumentacji Microsoft Power BI Desktop zapisuje pliki projektu z końcem linii CRLF i zaleca włączenie w Git ustawienia autocrlf. W naszej paczce kursu CRLF ma 158 ze 160 plików, wyjątkiem są dwa pliki zapytań DAX. Na komputerze z Windows wystarczy jedno polecenie.

   git config core.autocrlf true

6. Zdecyduj o pliku unappliedChanges.json. Gdy zespół nie chce w repozytorium niedokończonych zapytań Power Query, dopisz go do .gitignore, a przed zatwierdzeniem zastosuj albo odrzuć zmiany w Desktopie. Parametry zapytań, na przykład SciezkaPliku, zostają w expressions.tmdl i przechodzą do potoku wdrażania, co opisujemy w poście o regułach parametru w potoku wdrażania.
7. Sprawdź różnicę po pierwszej zmianie. W kursie zmiana formatu miary Marża po zwrotach % z dwóch miejsc po przecinku na jedno dała w pliku tables/FaktSprzedaz.tmdl jedną zmienioną linię, widoczną poniżej w zapisie różnic Git.

   -		formatString: 0.00%
   +		formatString: 0.0%

Jak sprawdzić, że problem zniknął

Sklonuj repozytorium do nowego folderu i otwórz plik .pbip. Według dokumentacji Microsoft Desktop bez pliku cache.abf otwiera raport z pełną definicją modelu, ale bez danych, więc puste wizualizacje są tu dowodem, że dane zostały poza repozytorium. Kliknij w Desktopie Odśwież, a model wczyta dane ze źródeł, do których masz dostęp. Gdy po sklonowaniu raport od razu pokazuje liczby, plik z danymi jest w repozytorium i trzeba go z niego wycofać.

Nie przechowuj projektu w folderze synchronizowanym z OneDrive, bo według dokumentacji może to powodować nieudane zapisy. Gdy edytujesz pliki TMDL poza Desktopem przy otwartym projekcie, Desktop według dokumentacji wykrywa zmianę i proponuje jej zastosowanie jednym kliknięciem. Komunikat o tym nie ma polskiego tłumaczenia: „This project's files were changed externally. Apply to view the latest changes.” Plik .pbip z kursu zawiera też ustawienie autoodzyskiwania, opisane w poście o odzyskiwaniu niezapisanego pliku po awarii. Rozmiar samego modelu z danymi kontrolujesz osobno, o czym piszemy w poście o pliku .pbix za dużym do publikacji.

Źródła i sposób sprawdzenia

• Microsoft Learn: Power BI Desktop projects (PBIP), struktura, .gitignore, ograniczenia (źródło)
• Microsoft Learn: Power BI Desktop project semantic model folder (cache.abf, localSettings.json, unappliedChanges.json) (źródło)
• Microsoft Learn: Power BI Desktop project report folder (źródło)
• Kurs Power BI, lekcja 26: projekt nordvella_26_pipeline.pbip, folder projektu, TMDL, paczka do pobrania bez cache.abf i localSettings.json

Zachowanie programu sprawdziliśmy w Power BI Desktop 2.157 (wydanie z sierpnia 2026 r.) z polskim interfejsem, a przykłady na modelu sieci Nordvella z bezpłatnego kursu Power BI. Microsoft wydaje nową wersję Power BI Desktop co miesiąc, więc nazwy przycisków i limity usługi mogą się zmieniać. Aktualne wartości podaje dokumentacja Microsoft Learn.

Wróć do listy: 131 najczęstszych pytań i problemów związanych z Power BI