Git Branching and Merging Explained — Strategies, Conflicts and Real-World Workflows

# ── Step 1: Initialise a fresh repo so we start clean ──────────────────────
git init branch-demo
cd branch-demo

# ── Step 2: Create an initial commit on main ────────────────────────────────
echo "v1: Initial homepage" > homepage.html
git add homepage.html
git commit -m "Add initial homepage"

# ── Step 3: See what a branch actually IS on disk ───────────────────────────
# Git stores the branch as a plain text file containing the commit hash
cat .git/refs/heads/main
# Output: a8f3c1d2e4b5f6a7b8c9d0e1f2a3b4c5d6e7f8a9  (your hash will differ)

# ── Step 4: Create a feature branch ────────────────────────────────────────
# This creates a NEW text file in .git/refs/heads/ — nothing more
git checkout -b feature/user-authentication

# ── Step 5: Confirm HEAD now points to the new branch, not main ─────────────
cat .git/HEAD
# Output: ref: refs/heads/feature/user-authentication

# ── Step 6: Make a commit on the feature branch ─────────────────────────────
echo "<form>Login form</form>" >> homepage.html
git add homepage.html
git commit -m "Add login form to homepage"

# ── Step 7: Check the branch graph — notice main is still at the old commit ─
git log --oneline --graph --all
# Output:
# * 3f9a2b1 (HEAD -> feature/user-authentication) Add login form to homepage
# * a8f3c1d (main) Add initial homepage

# ── Step 8: Switch back to main — homepage.html reverts to v1 instantly ─────
git checkout main
cat homepage.html
# Output: v1: Initial homepage

# ── SETUP: Create a scenario where main moved forward while we worked ────────
git init merge-rebase-demo
cd merge-rebase-demo

# Initial commit — shared starting point
echo "API v1" > api.js
git add api.js && git commit -m "Initial API setup"

# Teammate commits directly to main (simulating their merged PR)
git checkout -b simulate-teammate-work
echo "GET /users endpoint" >> api.js
git add api.js && git commit -m "Add GET users endpoint"
git checkout main
git merge simulate-teammate-work --no-ff -m "Merge: add GET users endpoint"

# Now WE start our feature branch from the OLD main
git checkout -b feature/add-auth-middleware main~1
echo "Auth middleware logic" > middleware.js
git add middleware.js && git commit -m "Add auth middleware"

# ── OPTION A: MERGE ──────────────────────────────────────────────────────────
# Brings main INTO our feature branch — preserves full history
# Creates a merge commit showing the two branch lines converging
git checkout feature/add-auth-middleware
git merge main -m "Merge main into feature/add-auth-middleware"

git log --oneline --graph
# Output shows a 'V' shape — two lines of work merging together:
# *   d4e5f6a Merge main into feature/add-auth-middleware
# |\  
# | * b2c3d4e Merge: add GET users endpoint
# | * 9a1b2c3 Add GET users endpoint
# * | 7f8e9d0 Add auth middleware
# |/  
# * 1a2b3c4 Initial API setup

# ── OPTION B: REBASE (reset to show alternative) ─────────────────────────────
# Pretend we haven't merged yet — re-create the branch from the old main
git checkout -b feature/add-auth-middleware-rebased main~1
echo "Auth middleware logic" > middleware.js
git add middleware.js && git commit -m "Add auth middleware"

# Rebase replays our commit ON TOP of main's latest commit
# Our commit gets a brand new SHA — it's a different object now
git rebase main

git log --oneline --graph
# Output shows a perfectly straight line — looks like no branching happened:
# * e5f6a7b Add auth middleware          <- NEW SHA, replayed commit
# * b2c3d4e Merge: add GET users endpoint
# * 9a1b2c3 Add GET users endpoint
# * 1a2b3c4 Initial API setup

# ── SETUP: Create a conflict scenario deliberately ──────────────────────────
git init conflict-demo
cd conflict-demo

# Both branches will start from this shared commit
echo "function calculateDiscount(price) {
  return price * 0.9;  // 10% discount for everyone
}" > discount.js
git add discount.js && git commit -m "Add basic discount calculation"

# ── Branch A: Marketing wants a 20% discount ────────────────────────────────
git checkout -b feature/marketing-discount
sed -i 's/price \* 0.9/price * 0.8/' discount.js  # 20% discount
git add discount.js && git commit -m "Increase discount to 20% for campaign"

# ── Branch B: Finance wants a 5% discount (back on main) ────────────────────
git checkout main
sed -i 's/price \* 0.9/price * 0.95/' discount.js  # 5% discount only
git add discount.js && git commit -m "Reduce discount to 5% per finance team"

# ── Attempt the merge — this WILL conflict ──────────────────────────────────
git merge feature/marketing-discount
# Git stops here and reports the conflict

# ── See what Git has put inside the conflicted file ─────────────────────────
cat discount.js
# Output:
# function calculateDiscount(price) {
# <<<<<<< HEAD
#   return price * 0.95;  // 10% discount for everyone
# =======
#   return price * 0.8;  // 10% discount for everyone
# >>>>>>> feature/marketing-discount
# }

# ── Resolve the conflict: agree on 15% as a compromise ──────────────────────
# In real life you'd open your editor — here we write the resolved version directly
cat > discount.js << 'EOF'
function calculateDiscount(price, isLoyalCustomer) {
  // Resolved: 15% for loyal customers (compromise between marketing and finance)
  const baseDiscount = isLoyalCustomer ? 0.85 : 0.95;
  return price * baseDiscount;
}
EOF

# ── Mark the conflict as resolved by staging the file ───────────────────────
git add discount.js

# ── Check status before committing — Git shows 'All conflicts fixed' ─────────
git status
# On branch main
# All conflicts fixed but you are still merging.
#   (use "git commit" to conclude merge)

# ── Finalise the merge with a meaningful commit message ─────────────────────
git commit -m "Merge feature/marketing-discount — compromise 15% loyal customer rate"

# ── Verify the clean history ─────────────────────────────────────────────────
git log --oneline --graph
# *   f1a2b3c Merge feature/marketing-discount — compromise 15% loyal customer rate
# |\  
# | * 4d5e6f7 Increase discount to 20% for campaign
# * | 8g9h0i1 Reduce discount to 5% per finance team
# |/  
# * 2j3k4l5 Add basic discount calculation

# ── TRUNK-BASED DEVELOPMENT: The workflow at high-velocity teams ─────────────
# Rule: feature branches live for 1-2 days max. Merge often. Deploy from main.

# ── Step 1: Always start from an up-to-date main ────────────────────────────
git checkout main
git pull origin main   # Never start work on stale code

# ── Step 2: Create a short-lived, focused feature branch ────────────────────
# This branch should do ONE thing. Not 'refactor everything.'
git checkout -b feature/PROJ-88-add-password-reset

# ── Step 3: Make small, atomic commits — each commit should be deployable ───
echo "POST /auth/password-reset" >> routes.js
git add routes.js
git commit -m "PROJ-88: Add password reset route"

echo "sendResetEmail(user.email, resetToken)" >> emailService.js
git add emailService.js
git commit -m "PROJ-88: Wire reset token to email service"

# ── Step 4: Rebase onto latest main before opening PR ───────────────────────
# This ensures your PR has zero conflicts when it lands
git fetch origin
git rebase origin/main
# If conflicts arise here, resolve them now — not after code review

# ── Step 5: Push and open a Pull Request ────────────────────────────────────
git push origin feature/PROJ-88-add-password-reset
# Open PR on GitHub/GitLab — request review — CI runs automatically

# ── Step 6: After approval, use SQUASH MERGE on GitHub/GitLab ───────────────
# Squash merge collapses all your commits into one clean commit on main
# This keeps main's history readable — one entry per feature
# Equivalent CLI command:
git checkout main
git merge --squash feature/PROJ-88-add-password-reset
git commit -m "PROJ-88: Add password reset flow (route + email service)"

# ── Step 7: Delete the branch — it has served its purpose ───────────────────
git branch -d feature/PROJ-88-add-password-reset
git push origin --delete feature/PROJ-88-add-password-reset

# ── Step 8: Deploy immediately — main is always production-ready ─────────────
# Your CI/CD pipeline triggers automatically on merge to main
echo "main is now deployed to production automatically via CI/CD"