fx

Modelagem

PBIP + Git

Versionar o projeto do Power BI com Git e VS Code: .gitignore, primeiro commit, rotina de commit, revisão e restauração, e cuidados com dados.

Atualizado em 03/10/2026. Conferido no Microsoft Learn (Power BI Desktop projects e Git integration). Na dúvida, confira os links no fim da página.

1. Por que versionar

Salvo como Power BI Project (.pbip), o relatório e o modelo deixam de ser um arquivo único e viram uma pasta de arquivos de texto: cada tabela, com suas medidas, fica num .tmdl (veja TMDL) e cada visual num visual.json (veja PBIR). Com o Git por cima:

  • você vê o que mudou, linha por linha, antes de gravar;
  • pode voltar uma medida ou um visual a uma versão anterior;
  • várias pessoas trabalham no mesmo projeto sem trocar .pbix por e-mail.

2. Antes de começar

O quêOndeCusto
Gitgit-scm.comGratuito
Visual Studio Codecode.visualstudio.comGratuito
Projeto no formato PBIPPower BI Desktop → Arquivo → Salvar como → tipo Power BI Project (*.pbip)—

3. O .gitignore

Ao salvar o projeto, o Desktop cria sozinho um .gitignore na pasta, se ainda não existir um, com estas linhas:

**/.pbi/localSettings.json
**/.pbi/cache.abf
  • localSettings.json guarda preferências da sua máquina.
  • cache.abf é o cache com os DADOS do modelo. ⚠️ Nunca versione esse arquivo.

Sem o cache.abf, o Desktop abre o modelo completo (tabelas, medidas, relacionamentos), só sem dados: basta atualizar para carregá-los de novo.

4. Passo a passo no VS Code

  1. No VS Code, Arquivo → Abrir pasta e escolha a pasta do projeto (a que contém o .pbip).
  2. Abra Source Control (ícone de ramificação na barra lateral, ou Ctrl + Shift + G).
  3. Clique em Initialize Repository.
  4. Escreva a mensagem do primeiro commit (por exemplo, Versão inicial do relatório de vendas) e clique em Commit.

5. Rotina mínima: 3 ações

5.1 Commit depois de cada mudança que funciona

Mudou uma medida, conferiu o resultado, faça o commit. A mensagem diz o porquê, não só o quê:

Medida Margem % passa a excluir devoluções

5.2 Revisar antes do commit

Em Source Control, clique no arquivo alterado para ver o diff. Uma medida alterada aparece só no .tmdl da tabela onde ela mora; se surgirem arquivos que você não esperava, investigue antes de gravar.

5.3 Voltar

⚠️ Sempre com o Power BI Desktop FECHADO.

Descartar alterações ainda não commitadas de um arquivo:

git restore <arquivo>

Restaurar um arquivo como estava num commit anterior:

git checkout <commit> -- <arquivo>

O <commit> é o código que aparece no histórico (git log --oneline). Depois, abra o .pbip de novo.

6. Cuidados

  • ⚠️ Feche o Power BI Desktop antes de trocar de branch, restaurar ou fazer pull. Sem o recurso em preview 'Detect and reload external PBIP changes' (Desktop agosto/2026), o Desktop só relê os arquivos ao abrir; com ele aberto, a próxima gravação sobrescreve o que o Git trouxe.
  • ⚠️ Repositório público: visual.json e os bookmarks podem guardar valores de dados (filtros, seleção de segmentação). E o unappliedChanges.json pode sobrescrever consultas editadas fora do Desktop. Revise esses arquivos antes de publicar o repositório.

7. Próximo passo

Com o projeto no Git, o caminho natural é a integração Git do Fabric (workspace ligado ao repositório) e pipelines de CI/CD. Para revisar o modelo com regras antes de cada commit, veja as Boas Práticas e a skill bi-qa-documentacao em Skills de IA.

Fontes