Branching And Merge Basics

Why this matters

As a BI Developer, you juggle SQL models, semantic layers, and dashboard definitions. Branching lets you isolate changes (like a new KPI or a hotfix) without breaking the main reports. Merging brings safe, reviewed work back into the main line so production stays stable.

• Ship a new metric without blocking teammates.
• Hotfix a broken report while ongoing features continue.
• Review and test changes before they reach production.

Concept explained simply

A branch is a movable pointer to a series of commits. You create a branch to do work safely. When done, you merge your branch back. If files changed in different ways, Git merges automatically. If the same lines changed in two places, you resolve a conflict, then complete the merge.

Mental model

Imagine a highway (main). Each exit is a branch where you can drive safely to explore. When the road is ready, you rejoin the highway at a merge ramp. If two cars try to use the same space at once (same lines), you coordinate (resolve conflicts) before merging.

Core terms you’ll use

• Main (or master): the stable branch.
• Feature branch: where you develop a change (e.g., new_metric_kpi).
• Commit: a snapshot of changes with a message.
• Merge: integrate changes from one branch into another.
• Fast-forward merge: main moves forward to include your commits without creating a new merge commit (no divergence).
• Merge commit: a special commit that combines two histories when both moved.
• Conflict: when the same lines changed differently; you must choose the final version.

Branch naming conventions (practical)

• feature/short-kpi-name
• fix/issue-id-short-desc
• chore/refactor-models

Use lowercase and hyphens. Keep names short but clear.

Worked examples

Example 1: Add a new KPI with a fast-forward merge

1. Start on main: git checkout main and ensure up to date: git pull.
2. Create a branch: git checkout -b feature/new-orders-kpi.
3. Edit models/orders_kpi.sql. Save.
4. Stage and commit: git add models/orders_kpi.sql then git commit -m "Add new orders KPI".
5. Return to main: git checkout main. If no new work happened on main, merge fast-forward: git merge feature/new-orders-kpi.
6. Result: main now includes your commits without a merge commit.

Example 2: Hotfix with a merge commit

1. Colleague changed report.sql on main while you worked in a branch.
2. You finish your fix in fix/missing-filter and commit.
3. Update main: git checkout main; git pull.
4. Merge your fix: git merge fix/missing-filter. Because main moved, Git creates a merge commit.
5. Write a clear merge message: what, why, any testing done.

Example 3: Resolve a merge conflict in a SQL model

1. Both branches changed the same WHERE clause in models/customers.sql.
2. On merging, Git marks conflict sections with <<<<<<< and >>>>>>>.
3. Edit the file to the correct logic, test the query locally (e.g., run in your SQL tool), then git add models/customers.sql.
4. Complete merge: git commit. A merge commit records the resolution.

Hands-on: your first branch

1. Ensure you have a repo with a main branch and at least one SQL file (e.g., queries/sales.sql).
2. Create branch: git checkout -b feature/sales-cte.
3. Edit the file (add a CTE or comment). Save.
4. Stage and commit: git add .; git commit -m "Refactor sales with CTE".
5. Switch to main: git checkout main and merge: git merge feature/sales-cte.
6. Optional: delete branch after merge: git branch -d feature/sales-cte.

Common mistakes and self-check

• Working directly on main. Self-check: Does git status show you are on a feature branch before editing?
• Vague commit messages. Use "verb + object + why" (e.g., "Add orders KPI to support weekly dashboard").
• Forgetting to pull before merging. Always git pull on main first to reduce conflicts.
• Accidentally committing generated files. Add them to .gitignore (e.g., target/, .DS_Store).

Exercises

Complete the exercises below. A matching answer section is at the bottom of this page. Do them in any Git repository with a main branch.

• Exercise 1: Fast-forward merge a feature branch back to main.
• Exercise 2: Create and resolve a merge conflict, then finish the merge.

Exercise checklist

• You created a branch with a clear name.
• You made at least one commit with a clear message.
• You merged back into main and verified history.
• You practiced resolving a conflict safely.

Practical projects (BI-focused)

• Project 1: KPI rollout. On a feature branch, add a new KPI SQL model and a semantic layer change. Merge when validated.
• Project 2: Hotfix filters. Create a fix branch to correct a WHERE clause causing inflated counts. Add a test query and merge.
• Project 3: Dashboard theme switch. Keep JSON/YAML/Theme files in version control. Branch to update theme tokens, then merge after visual review.

Who this is for

• BI Developers and Analytics Engineers who version SQL, models, and dashboards.
• Data team members contributing to shared repositories.

Prerequisites

• Basic Git: init/clone, status, add, commit.
• Comfort editing files and running shell commands.

Learning path

• Before: Git basics (clone, commit).
• Now: Branching and merge basics (this lesson).
• Next: Pull requests and code review; Branching strategies (feature, release, hotfix); Tagging releases and revert basics.

Mini challenge

Create two branches in parallel: one adds a column to a model; another renames that column. Merge them back into main in a safe order, resolving any conflicts. Write down what you learned about sequencing changes.

Progress and test

The quick test below is available to everyone. Only logged-in users will have their progress saved.

Exercise 1 — Fast-forward merge (solution)

See the Exercises section for the task. A full reference solution is provided in the Exercise solutions below.

Exercise 2 — Conflict resolution (solution)

See the Exercises section for the task. A full reference solution is provided in the Exercise solutions below.