Versionamento Power BI
com Git & GitHub

Para o perfil Intermediário, instale o stack profissional completo. O VS Code é a ferramenta central — combina edição de TMDL/JSON, Git visual (Source Control) e terminal integrado.

1. Git for Windows

   Instale em git-scm.com. Inclui Git Bash e integração com PowerShell.

   powershell

   # verificar instalação
   git --version
   # saída esperada: git version 2.45.x

2. Configurar identidade Git (uma vez só)

   bash

   git config --global user.name "Seu Nome"
   git config --global user.email "voce@empresa.com"
   git config --global init.defaultBranch main
   git config --global core.autocrlf true
   git config --global pull.rebase false
   # para Windows: prefere editor padrão do VS Code
   git config --global core.editor "code --wait"

3. VS Code + extensões

   Baixe em code.visualstudio.com. Extensões essenciais para o stack PBI + Git:

   Extensão	Para que serve
   GitLens	Mostra blame, autoria e histórico inline em cada linha
   Git Graph	Visualiza o gráfico de commits e branches em árvore
   Git History	Histórico amigável de arquivos individuais
   TMDL (powerbi-tools)	Syntax highlight para arquivos de modelo semântico
   Power BI Studio	Suporte ampliado a PBIP/PBIR
   Better TOML / YAML	Para arquivos de configuração e CI/CD

   powershell

   # instalar extensões via terminal (após VS Code estar no PATH)
   code --install-extension eamodio.gitlens
   code --install-extension mhutchie.git-graph
   code --install-extension donjayamanne.githistory

4. Autenticação no GitHub

   Duas opções (escolha uma):

   • Personal Access Token (PAT) — recomendado para começar. Gere em github.com → Settings → Developer settings → Personal access tokens. Cole quando o Git pedir senha.
   • SSH Key — mais profissional. Gere com ssh-keygen -t ed25519 -C "voce@empresa.com" e adicione a chave pública em github.com → Settings → SSH keys.

5. Power BI Desktop com PBIP habilitado

   Arquivo › Opções › Visualizações › Power BI Project (.pbip). Reinicie o Power BI após habilitar.

Via terminal (PowerShell ou Bash)

git clone https://github.com/empresa/relatorio-vendas-powerbi.git
cd relatorio-vendas-powerbi
git status

Via VS Code

1. Pressione Ctrl+Shift+P e digite Git: Clone
2. Cole a URL HTTPS do repositório
3. Escolha a pasta local
4. Aceite "Open repository"

6 VS Code — IDE para o fluxo intermediário

O VS Code combina três coisas que você precisa no dia a dia: editor de código (TMDL, JSON, README), controle de código-fonte visual (Source Control / SCM) e terminal integrado (PowerShell ou Bash). Você pode usar tudo por GUI, tudo por terminal, ou misturar.

Anatomia do painel Controle do Código-Fonte

Abra com Ctrl + Shift + G. É o ícone com duas bolinhas e uma linha (3º na barra de atividades).

Painel Controle do Código-Fonte do VS Code com 7 alterações em um projeto PBIP.

Os dois caminhos: GUI vs Terminal

No VS Code você pode fazer a mesma operação de duas formas. Use o que for mais rápido em cada momento.

Significado de cada letra ao lado do arquivo

Ações rápidas no painel Source Control

Painel Gráfico (Git Graph)

Logo abaixo das alterações, com a extensão Git Graph instalada, você vê a árvore de commits. Cada bolinha colorida é um commit; as etiquetas mostram em qual branch cada commit está. Clique com botão direito sobre um commit para reverter, criar branch ou fazer cherry-pick.

Workflow recomendado no VS Code (passo a passo)

1. Abrir a pasta do projeto

   Ctrl + K, Ctrl + O ou Arquivo → Abrir Pasta. Selecione a raiz do repositório clonado.

2. Atualizar antes de começar

   No painel SCM, clique em ··· → Pull (ou no terminal: git pull).

3. Criar branch de trabalho

   Clique no nome da branch na barra de status (canto inferior esquerdo) → Create new branch… → digite feature/dashboard-vendas.

   # equivalente no terminal PS > git checkout -b feature/dashboard-vendas

4. Trabalhar no Power BI Desktop

   Abra o .pbip, faça as alterações, salve. Os arquivos .tmdl e .json serão atualizados em disco.

5. Revisar o diff no VS Code

   Volte para o VS Code. Clique em cada arquivo modificado no painel SCM — abre o diff lado a lado com a versão anterior. Confira que não está commitando lixo (cache, bookmarks).

6. Commit + Push

   Mensagem no padrão (feat: …) → Ctrl + Enter → clique no ícone de nuvem para fazer push.

7. Abrir Pull Request

   Clique no link que aparece como notificação, ou abra o GitHub Web manualmente. (Com a extensão GitHub Pull Requests, dá pra abrir o PR sem sair do VS Code.)

Configurações do VS Code recomendadas para PBI

Adicione no .vscode/settings.json do projeto (ou nas configurações globais):

{
  "git.autofetch": true,
  "git.confirmSync": false,
  "git.enableSmartCommit": true,
  "git.postCommitCommand": "push",
  "git.suggestSmartCommit": false,
  "scm.defaultViewMode": "tree",
  "diffEditor.ignoreTrimWhitespace": false,
  "files.eol": "\n",
  "files.exclude": {
    "**/*.pbix": true,
    "**/cache.abf": true,
    "**/localSettings.json": true
  }
}

Via terminal

# 1. Conferir o que vai entrar
git status

# 2. Adicionar tudo o que não está no .gitignore
git add .

# 3. Criar o commit
git commit -m "chore: estrutura inicial do projeto Power BI"

# 4. Enviar para o GitHub
git push

Comandos PowerShell e Bash

Sequência completa em uma branch nova

# 1. Atualizar a main
git checkout main
git pull

# 2. Criar branch nova a partir da main atualizada
git checkout -b feature/dashboard-vendas

# 3. (editar arquivos no Power BI Desktop, salvar)

# 4. Commit + push
git add .
git commit -m "feat: cria página de análise de vendas"
git push -u origin feature/dashboard-vendas

Comandos de rollback

Reverter o último commit (já publicado)

git revert HEAD
git push

Reverter um commit específico

git log --oneline   # pegue o hash
git revert <hash>
git push

Desfazer último commit local sem perder mudanças

git reset --soft HEAD~1

Desfazer último commit local apagando mudanças

git reset --hard HEAD~1

Recuperar estado antigo em uma branch nova (seguro)

git checkout -b baseline-recuperado <hash>

Reset com força no remoto (perigoso, só uso pessoal)

git reset --hard <hash>
git push --force

Comandos úteis

# Ver arquivos com conflito
git status

# Após resolver manualmente, marcar como resolvido
git add caminho/arquivo
git commit -m "fix: resolve conflito de merge na medida"

# Abortar o merge e voltar ao estado anterior
git merge --abort

Template Intermediário

# Nome do Projeto Power BI

## Objetivo
Descreva o objetivo de negócio do relatório e o público-alvo.

## Stack
- Power BI Desktop (PBIP habilitado)
- TMDL para modelo semântico
- Git + GitHub para versionamento
- VS Code com extensões GitLens, Git Graph, Power BI TMDL
- Power BI Service (workspace: `nome-do-workspace`)

## Estrutura do projeto
```
Projeto/
├── Projeto.pbip
├── Projeto.Report/
│   └── definition/
├── Projeto.SemanticModel/
│   └── definition/
├── README.md
└── .gitignore
```

## Fluxo de trabalho
1. `git checkout main && git pull`
2. `git checkout -b feature/sua-mudanca`
3. Editar no Power BI Desktop e salvar
4. `git add . && git commit -m "feat: descrição"`
5. `git push -u origin feature/sua-mudanca`
6. Abrir Pull Request, aguardar review
7. Merge na main após aprovação
8. Publicar manualmente no Power BI Service (versão aprovada)

## Convenção de commits
| Tipo | Uso |
|---|---|
| feat | Nova funcionalidade |
| fix | Correção |
| refactor | Reorganização |
| docs | Documentação |
| chore | Ajuste técnico |

## Workspaces
- DEV: `workspace-dev-relatorio`
- HML: `workspace-hml-relatorio`
- PRD: `workspace-prd-relatorio`

## Fontes de dados
- SQL Server: `servidor.empresa.local`
- Gateway: `Gateway-Corporativo-01`

## Responsável técnico
Nome: [Seu nome]
E-mail: [seu@email.com]
Data da última revisão: AAAA-MM-DD

Comandos essenciais — terminal