Power BI Version Control with Git: A Practical Guide

"We lost three weeks of changes because someone saved over the wrong file."

If you've worked in a team that shares .pbix files via SharePoint, OneDrive, or a network drive, you've either heard this or lived it. Binary files and human workflows don't mix well.

Git solves this problem for code. And with PBIP format, it can solve it for Power BI too. Here's how to set it up in a way that actually works for BI teams — even if Git is new to your organisation.

Prerequisites

Before anything else, you need:

1. Power BI Desktop (recent version that supports PBIP save)
2. Git installed on your machine (git-scm.com)
3. A Git hosting service — GitHub, Azure DevOps, GitLab, or Bitbucket
4. Your report saved in PBIP format (File → Save As → Power BI Project)

If your report is currently a .pbix file, resaving as PBIP is non-destructive. You'll get a folder structure with text files that represent your model, report, and data source definitions.

Initial repository setup

Navigate to your PBIP project folder in a terminal:

cd "My Reports/Sales Dashboard"
git init

The .gitignore file

Not everything in the PBIP folder should be committed. Create a .gitignore file:

# Power BI local cache and temporary files
*.pbi
.pbi/
localSettings.json
diagramLayout.json

# Data files (don't commit actual data)
*.abf
*.zip

# OS files
.DS_Store
Thumbs.db
desktop.ini

The key exclusions:

• .pbi/ folder — Contains local cache and user-specific settings. Committing it causes constant merge conflicts.
• localSettings.json — Stores your personal gateway and connection settings. Machine-specific, not shareable.
• diagramLayout.json — Saves the visual layout of the model diagram view. It changes every time you rearrange tables in the diagram, creating noise in your diffs.

Everything else — TMDL files, PBIR JSON files, M expressions — should be committed.

First commit

git add -A
git commit -m "Initial commit: Sales Dashboard PBIP"

Push to your remote:

git remote add origin https://github.com/your-org/sales-dashboard.git
git push -u origin main

Daily workflow

The workflow mirrors how developers use Git:

1. Pull before you start working: git pull
2. Open your PBIP project in Power BI Desktop
3. Make changes — add visuals, modify measures, adjust data sources
4. Save in Power BI Desktop (this writes the TMDL and PBIR files to disk)
5. Review the diff: git diff to see exactly what changed
6. Commit with a meaningful message: git commit -am "Add YTD comparison to executive page"
7. Push: git push

The crucial difference from working with .pbix is step 5. Now you can see that a commit changed one measure's DAX, added two columns, and modified a visual's filter — instead of just "binary file changed."

Branching strategy

For small teams (2-3 people), a simple approach works:

• main branch is the production version of the report
• Feature branches for each change: feature/add-regional-breakdown, fix/ytd-calculation
• Merge via pull request so someone reviews the changes

For BI teams who've never used branches, the mental model is: "I'm making a copy of the report to try something, and if it works, I'll merge it back." It's what people do already with file copies, but with history and a structured merge process.

Handling merge conflicts

The good news: because TMDL splits tables into separate files, two people working on different tables almost never conflict. Person A modifies Sales.tmdl while Person B modifies Product.tmdl — clean merge.

The bad news: if two people modify the same measure simultaneously, you'll get a conflict in that table's TMDL file. Git will mark the conflicting lines, and someone needs to pick the right version.

In practice, this is rare. Most conflicts happen in the report definition (PBIR JSON files) when two people edit visuals on the same page. The resolution is usually straightforward — you can read the JSON and choose which visual configuration to keep.

What good commit messages look like

Bad: "Updated report" Bad: "Changes" Bad: "WIP"

Good: "Add customer churn rate measure and KPI card on retention page" Good: "Fix: Sales YTD was using calendar year instead of fiscal year" Good: "Remove unused columns from Product dimension table (reduces model size by 15%)"

Good commit messages create a changelog of your report's evolution. Six months from now, you can look at the history and understand why each change was made.

Integrating with your tool stack

Once your PBIP reports are in Git, other things become possible:

• Pull request reviews: Before a change goes to production, someone else reviews it. This catches mistakes early.
• Automated validation: CI/CD pipelines can parse TMDL files and check for common issues — unused measures, naming convention violations, or DAX anti-patterns.
• Deployment pipelines: Promote a report from development to production by merging a branch, triggering a deployment workflow.
• Audit trail: Who changed what, when, and why — built into the Git history.

Tools like Dummy BI Automate can generate diffs between two versions of a PBIP project, showing changes at the semantic level (which measures changed, which visuals were added) rather than raw text differences. This makes code reviews accessible to people who don't want to read TMDL syntax.

Common mistakes to avoid

Don't commit after every save in Power BI Desktop. Power BI sometimes touches files you didn't intentionally modify (layout files, annotation timestamps). Save, review the diff, and only stage the files that represent real changes.

Don't put multiple reports in one repository (unless they share a dataset). One report per repo keeps things clean and avoids confusion about which changes affect which report.

Don't skip the .gitignore. The .pbi/ cache folder alone generates dozens of unnecessary changes on every save.

Don't force everyone to learn the command line. GitHub Desktop, VS Code's Git integration, and Azure DevOps' web interface all work fine. The tool doesn't matter — the workflow does.

Getting started with an existing report

If you have a .pbix report that's been in production for months:

1. Open it in Power BI Desktop
2. Save as PBIP
3. Initialise a Git repo in the new folder
4. Commit everything
5. Start using the workflow from your next change

There's no need to rewrite or restructure anything. PBIP is just a different serialisation of the same report. The semantic model, visuals, filters — everything is preserved.

The hardest part is the habit change. Once your team commits to using Git for a month, going back to shared file drives feels like going back to paper.