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
.pbixpor e-mail.
2. Antes de começar
| O quê | Onde | Custo |
|---|---|---|
| Git | git-scm.com | Gratuito |
| Visual Studio Code | code.visualstudio.com | Gratuito |
| Projeto no formato PBIP | Power 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.jsonguarda preferências da sua máquina.cache.abfé o cache com os DADOS do modelo. Atenção 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
- No VS Code, Arquivo → Abrir pasta e escolha a pasta do projeto (a que
contém o
.pbip). - Abra Source Control (ícone de ramificação na barra lateral, ou Ctrl + Shift + G).
- Clique em Initialize Repository.
- 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
Atenção 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
- Atenção 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.
- Atenção Repositório público:
visual.jsone os bookmarks podem guardar valores de dados (filtros, seleção de segmentação). E ounappliedChanges.jsonpode 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.