Source Control

bi-solution/
├─ datasets/
│  ├─ sales_model/             # folder-format model (model.json, tables, measures)
│  └─ finance_model/
├─ reports/
│  ├─ SalesReport.pbit         # template without data (version this)
│  └─ FinanceReport.pbit
├─ sql/
│  ├─ staging/
│  └─ marts/
├─ docs/
│  └─ release-notes.md
└─ .gitignore

Goal: Set up a Git repo that versions text-first BI assets while avoiding large binary files.

# in your project folder
git init

# recommended .gitignore for BI
# Large cache files or local data should not be committed
# Prefer .pbit (template) over .pbix when possible
*.pbix
*.pbix.cache
*.pqx.cache
*.pbids
.DS_Store
*.tmp

# Commit the structure and sample assets
git add datasets/ reports/*.pbit sql/ docs/ .gitignore
git commit -m "Init repo with datasets, reports templates, and SQL"

Tip: For Power BI datasets, export or maintain the model in folder format (model.json + subfolders) so changes are line-diffable.

# create a feature branch for a new visual
git switch -c feature/add-top-products-visual

# edit reports/SalesReport.pbit and datasets/sales_model/measures.json

git add reports/SalesReport.pbit datasets/sales_model/
git commit -m "Add Top Products visual + TotalProfit measure"

git push -u origin feature/add-top-products-visual

# open a pull request in your Git platform (UI) and request review
# after approval
# (from main branch)
git switch main
git pull

# merge via fast-forward or merge commit
# (often done in the platform UI)

Guideline: Keep branches small and focused (one feature or bugfix) to simplify reviews and rollbacks.

Suppose you add a calculated column and a measure. In folder format, your diff might look like:

diff --git a/datasets/sales_model/tables/Orders.json b/datasets/sales_model/tables/Orders.json
@@
 {"name": "Orders", "columns": [
-  {"name": "OrderDate", "dataType": "date"}
+  {"name": "OrderDate", "dataType": "date"},
+  {"name": "OrderYear", "expression": "YEAR([OrderDate])", "dataType": "int"}
 ]}

diff --git a/datasets/sales_model/measures.json b/datasets/sales_model/measures.json
@@
- []
+ [{"name": "TotalProfit", "expression": "SUMX(Orders, Orders[Revenue]-Orders[Cost])"}]

Reviewers can see exactly what changed and comment accordingly.

# after merging features into main and validating in Dev

# create a release branch
git switch -c release/2025-03-15

# bump version in docs/release-notes.md and finalize

git add docs/release-notes.md
git commit -m "Chore: prep release 2025-03-15"

git tag -a v2025.03.15 -m "Release to Stage"

git push origin release/2025-03-15 --tags

# deploy to Stage from this tag/branch, validate, then promote to Prod

Keep Stage stable for UAT. Only promote to Prod after sign-off.

# create a new commit that undoes a problematic change
# keeps history intact

git revert <bad_commit_sha>

git push

# or restore a file from a previous commit into main

git checkout <good_commit_sha> -- datasets/sales_model/measures.json

git commit -m "Restore measures from <good_commit_sha>"

git push

Prefer revert over destructive reset on shared branches.

<<<<<<< HEAD
{"name":"TotalProfit","expression":"SUM(Revenue) - SUM(Cost)"}
=======
{"name":"TotalProfit","expression":"SUMX(Orders, Orders[Revenue]-Orders[Cost])"}
>>>>>>> feature/refine-profit

Decide the correct logic, edit to a single, valid JSON object, and re-run tests in Dev. Then:

git add datasets/sales_model/measures.json
git commit -m "Resolve conflict: finalize TotalProfit measure"

Prefer .pbit templates and model folder-format. If you must store .pbix, keep them small and use LFS if required, with clear policies.

Do not commit passwords or keys. Use parameters, environment variables, or managed connections. Add known secret files to .gitignore.

Keep branches short-lived. Merge or close stale branches weekly. Rebase/merge frequently to avoid painful conflicts.

Write concise titles and descriptions: what changed, why, how to validate. Include screenshots for visual changes and sample queries for measure logic.

Record the impact on users, datasets, measures, and breaking changes. This speeds up incident response later.