Hands-on lab — Day 31: Branching and Merging

#!/usr/bin/env bash
# Day 031 lab — completed reference implementation.
#
# "Branch, Conflict, Merge": builds a throwaway git repository in a temporary
# directory, then walks through the whole branching story end to end:
#
#   1. a base commit on the default branch
#   2. a feature branch that edits some lines
#   3. a competing edit to the SAME lines back on the default branch
#   4. a three-way merge that COLLIDES -> a real conflict
#   5. a programmatic conflict resolution (git add + git commit)
#   6. git log --graph to see the diamond shape the merge created
#   7. a separate branch that merges cleanly as a FAST-FORWARD
#
# Everything is local: no network, no GitHub, no credentials. The temporary
# repository is deleted on exit, so running this leaves your machine untouched.
set -euo pipefail

# --- Make a private, disposable workspace ------------------------------------
# mktemp -d creates a fresh directory with a random name. We remove it on exit
# (success OR failure) via a trap, so nothing lingers.
workdir="$(mktemp -d "${TMPDIR:-/tmp}/day031-branch-merge.XXXXXX")"
cleanup() { rm -rf "${workdir}"; }
trap cleanup EXIT

echo "=== Branch, Conflict, Merge ==="
echo "Workspace: ${workdir}"
echo

cd "${workdir}"

# --- Step 0: a repository with a LOCAL identity ------------------------------
# git init makes the current directory a repository. We set user.name and
# user.email with --local so this identity applies ONLY to this throwaway repo
# and never touches your real global git config. -b main names the first
# branch "main" so the output is predictable across git versions.
git init -q -b main
git config --local user.name "Day 31 Learner"
git config --local user.email "learner@example.invalid"

echo "--- Step 1: base commit on main ---"
# A tiny recipe file is our shared document. Everyone starts from this version.
printf '%s\n' \
  "# Pancakes" \
  "flour: 1 cup" \
  "milk: 1 cup" \
  "eggs: 1" > recipe.txt
git add recipe.txt
git commit -q -m "Add base pancake recipe"
git log --oneline
echo

# --- Step 2: a feature branch that changes a line ----------------------------
echo "--- Step 2: create feature branch 'feature-blueberries' and edit line 3 ---"
git switch -q -c feature-blueberries
# On the feature branch we double the milk. This rewrites line 3.
printf '%s\n' \
  "# Pancakes" \
  "flour: 1 cup" \
  "milk: 2 cups" \
  "eggs: 1" > recipe.txt
git commit -q -am "feature: use 2 cups of milk"
echo "feature-blueberries now says:"
sed -n '3p' recipe.txt
echo

# --- Step 3: a COMPETING edit to the same line, back on main -----------------
echo "--- Step 3: back on main, edit the SAME line 3 differently ---"
git switch -q main
# On main someone else changes line 3 to buttermilk instead. Two branches,
# two different values for the same line: this is what makes a conflict.
printf '%s\n' \
  "# Pancakes" \
  "flour: 1 cup" \
  "milk: 1 cup buttermilk" \
  "eggs: 1" > recipe.txt
git commit -q -am "main: switch to buttermilk"
echo "main now says:"
sed -n '3p' recipe.txt
echo

# --- Step 4: merge the feature branch -> a real three-way merge conflict -----
echo "--- Step 4: merge feature-blueberries into main (expect a conflict) ---"
# We want the merge to FAIL with a conflict, but 'set -e' would abort the
# script on git merge's non-zero exit. Guard it so we can react instead.
if git merge --no-edit feature-blueberries; then
  echo "Unexpected: the merge succeeded without a conflict." >&2
  exit 1
fi

echo
echo "Conflict detected. git status shows the unmerged file:"
git status --short
echo
echo "Git rewrote recipe.txt with conflict markers:"
cat recipe.txt
echo

# --- Step 5: resolve the conflict programmatically ---------------------------
echo "--- Step 5: resolve the conflict, then add + commit ---"
# A human would open the file and edit out the markers by hand. To keep this
# script deterministic we write the resolved file directly: we KEEP BOTH
# ideas — buttermilk AND more of it — which is a real editorial decision, not
# a blind "take theirs". The three marker lines (<<<<<<<, =======, >>>>>>>)
# are gone; that is what "resolved" means.
printf '%s\n' \
  "# Pancakes" \
  "flour: 1 cup" \
  "milk: 2 cups buttermilk" \
  "eggs: 1" > recipe.txt

# Prove no conflict markers remain before we stage the file.
if grep -qE '^(<<<<<<<|=======|>>>>>>>)' recipe.txt; then
  echo "Conflict markers still present — resolution incomplete." >&2
  exit 1
fi

git add recipe.txt          # staging the file tells git "this conflict is handled"
git commit --no-edit -q     # completes the merge; creates the MERGE COMMIT
echo "Resolved. Final recipe:"
cat recipe.txt
echo

# --- Step 6: view the history as a graph -------------------------------------
echo "--- Step 6: history graph (the merge commit ties both lines together) ---"
git log --graph --oneline
echo

# --- Step 7: a clean FAST-FORWARD merge on a separate branch -----------------
echo "--- Step 7: a clean fast-forward merge (no divergence, no conflict) ---"
# Branch off, add a brand-new file (touches nothing main changed), come back.
# Because main has not moved since we branched, git can merge by simply sliding
# main's pointer forward to the feature commit: a fast-forward, no merge commit.
git switch -q -c feature-notes
printf '%s\n' "Serve warm with syrup." > serving.txt
git add serving.txt
git commit -q -m "feature: add serving suggestion"
git switch -q main
git merge --ff-only feature-notes
echo
echo "History after the fast-forward (feature-notes just extends the line):"
git log --graph --oneline
echo

echo "=== Done. Temporary repository will be deleted on exit. ==="

lesson_id: D031
day: 31
kind: command-line-inspection
languages: [bash]
setup_commands:
  - cd labs/sections/computing-foundations/day-031-branching-and-merging
run_commands:
  - bash examples/branch_merge.sh
  - bash starter/branch_merge.sh
test_commands:
  - bash tests/run_tests.sh
cleanup_commands:
  - 'none — each script deletes its own temporary repository on exit'
requires_network: false
requires_api_key: false
estimated_minutes: 30
last_executed: '2026-07-12'
executed_on: 'macOS (Apple Silicon), git 2.50.1, bash tests/run_tests.sh → 10 checks, 0 failures'

# Dependencies — Day 031 lab

**One tool: `git`.** Nothing else is installed, downloaded, or configured.

- `git` ≥ 2.23 (for `git switch`; released August 2019). Check with
  `git --version`. On older git, the lab still works with `git checkout`
  substitutions documented in `troubleshooting.md`.
- `bash` ≥ 3.2 (preinstalled on macOS and every mainstream Linux distribution)
  and the standard utilities `mktemp`, `printf`, `sed`, `grep` — all part of
  the base system.

There is deliberately no `requirements.txt` or `package.json`: the lab creates
a throwaway repository in a temporary directory and needs no project of its
own.

## Installing git (if `git --version` fails)

- **macOS:** `xcode-select --install` (installs the Command Line Tools, which
  include git), or install from the official git website.
- **Debian/Ubuntu:** `sudo apt update && sudo apt install git`
- **Fedora:** `sudo dnf install git`
- **Windows:** install Git for Windows, or run this lab inside WSL and use the
  Linux path.

No network access is required to run the lab itself — only, possibly, to
install git the first time.

#!/usr/bin/env bash
# Day 031 lab — YOUR working file: "Branch, Conflict, Merge".
#
# This starter builds a throwaway git repository for you and makes the base
# commit. Your job is to complete the five numbered exercises below by filling
# in the exact git commands named in each comment, replacing every line that
# says:  echo "EXERCISE N -- replace this line ...".
#
# The finished reference version is in examples/branch_merge.sh — try the
# exercises yourself first, then compare.
#
# Everything is local and offline. The temporary repository is deleted on exit,
# so you can run this as many times as you like without touching your machine.
set -euo pipefail

# --- A private, disposable workspace (already done for you) -------------------
workdir="$(mktemp -d "${TMPDIR:-/tmp}/day031-starter.XXXXXX")"
cleanup() { rm -rf "${workdir}"; }
trap cleanup EXIT
cd "${workdir}"

echo "=== Branch, Conflict, Merge (starter) ==="
echo "Workspace: ${workdir}"
echo

# --- Repo with a LOCAL identity + base commit (already done for you) ----------
git init -q -b main
git config --local user.name "Day 31 Learner"
git config --local user.email "learner@example.invalid"
printf '%s\n' "# Pancakes" "flour: 1 cup" "milk: 1 cup" "eggs: 1" > recipe.txt
git add recipe.txt
git commit -q -m "Add base pancake recipe"
echo "Base commit made on main. recipe.txt line 3 is: $(sed -n '3p' recipe.txt)"
echo

# =============================================================================
# EXERCISE 1 — create and switch to a feature branch.
# Use ONE command that both creates the branch and moves onto it:
#     git switch -c feature-blueberries
# (older git: git checkout -b feature-blueberries)
# Replace the placeholder line below with that command.
# =============================================================================
echo "EXERCISE 1 (replace this line): create and switch to branch feature-blueberries with git switch -c"

# On the feature branch, change line 3 to "milk: 2 cups", then commit it.
printf '%s\n' "# Pancakes" "flour: 1 cup" "milk: 2 cups" "eggs: 1" > recipe.txt
git commit -q -am "feature: use 2 cups of milk"
echo "On feature branch, line 3 is now: $(sed -n '3p' recipe.txt)"
echo

# =============================================================================
# EXERCISE 2 — switch back to main.
# Use:  git switch main   (older git: git checkout main)
# Replace the placeholder line below with that command.
# =============================================================================
echo "EXERCISE 2 (replace this line): switch back to main with git switch main"

# Back on main, change the SAME line 3 differently, then commit it. Two branches
# now disagree about line 3 — the setup for a conflict.
printf '%s\n' "# Pancakes" "flour: 1 cup" "milk: 1 cup buttermilk" "eggs: 1" > recipe.txt
git commit -q -am "main: switch to buttermilk"
echo "On main, line 3 is now: $(sed -n '3p' recipe.txt)"
echo

# =============================================================================
# EXERCISE 3 — merge the feature branch into main.
# Use:  git merge --no-edit feature-blueberries
# This WILL report a conflict — that is expected and correct. Because the
# script uses 'set -e', wrap the command so a conflict does not abort us:
#     git merge --no-edit feature-blueberries || true
# Replace the placeholder line below with that guarded command.
# =============================================================================
echo "EXERCISE 3 (replace this line): merge feature-blueberries into main with git merge --no-edit (guard with || true)"

echo
echo "git status after the merge attempt:"
git status --short
echo
echo "recipe.txt now contains conflict markers:"
cat recipe.txt
echo

# =============================================================================
# EXERCISE 4 — resolve the conflict.
# A real resolution removes the three marker lines (<<<<<<<, =======, >>>>>>>)
# and leaves the wording you want. Here we keep BOTH ideas. Replace the
# placeholder line below with a command that writes the resolved line 3, e.g.:
#     printf '%s\n' "# Pancakes" "flour: 1 cup" "milk: 2 cups buttermilk" "eggs: 1" > recipe.txt
# =============================================================================
echo "EXERCISE 4 (replace this line): write the resolved recipe.txt (line 3 = milk: 2 cups buttermilk, no markers)"

echo "recipe.txt after your resolution:"
cat recipe.txt
echo

# =============================================================================
# EXERCISE 5 — stage the resolved file and complete the merge.
# Two commands: stage the file, then commit to create the merge commit:
#     git add recipe.txt
#     git commit --no-edit
# Replace the placeholder line below with those two commands.
# =============================================================================
echo "EXERCISE 5 (replace this line): run git add recipe.txt then git commit --no-edit to finish the merge"

echo
echo "Final history graph:"
git log --graph --oneline
echo
echo "=== Done. Temporary repository will be deleted on exit. ==="

# Branching worksheet — Day 031

Fill this in from your own run of `starter/branch_merge.sh` (after you have
completed the five exercises) or from your own hand-typed experiment. Keep it —
Week 5's project (the Versioned Notes Repository) reuses exactly these moves.

## Branches I created

| Branch name | Created with (command) | What I changed on it |
| ----------- | ---------------------- | -------------------- |
|             |                        |                      |
|             |                        |                      |

## The merge I performed

| Question | My answer |
| -------- | --------- |
| Which branch did I merge INTO? |  |
| Which branch did I merge IN? |  |
| Was it a **fast-forward** or a **three-way** merge? |  |
| How do I know? (merge commit created? `|\` diamond in the graph?) |  |

> Reminder: a **fast-forward** happens when the target branch has not moved
> since you branched, so git just slides its pointer forward — no merge commit.
> A **three-way merge** happens when both branches advanced, so git builds a
> new merge commit with two parents (and may hit a conflict on the way).

## The conflict I resolved

Paste the exact conflict block git wrote into the file (the three marker lines
and the two competing versions between them):

```text
<<<<<<< HEAD

=======

>>>>>>>
```

- The version above `=======` came from branch: ____________________
- The version below `=======` came from branch: ____________________
- The resolution I chose (kept theirs / kept mine / blended both): ___________
- The final line I committed: ____________________________________________

## One sentence: why did this conflict happen?

_(Hint: what did the two branches both do to the same line?)_

#!/usr/bin/env bash
# Tests for the Day 031 lab. Run from the lab directory:
#   bash tests/run_tests.sh
#
# These tests build their OWN throwaway repository in a temp directory and
# drive the same branch -> conflict -> resolve -> merge story the lab teaches,
# then assert on the resulting git state:
#   * a feature branch was created
#   * merging it produced a real conflict
#   * the conflict was resolved and the repo ends CLEAN
#   * the final history contains a real merge commit (two parents)
#   * git log --graph renders the merge (the |\ diamond)
#
# Everything is local and offline. The temp repo is deleted on exit.
set -u

# Resolve the lab directory BEFORE we change into the temp workspace, because
# BASH_SOURCE becomes a relative path once we cd elsewhere.
lab_dir="$(cd "$(dirname "${BASH_SOURCE[0]}")/.." && pwd)"

failures=0
checks=0

check() {
  local label="$1" ok="$2"
  checks=$((checks + 1))
  if [ "${ok}" = "yes" ]; then
    echo "  ok: ${label}"
  else
    echo "  FAIL: ${label}"
    failures=$((failures + 1))
  fi
}

# Refuse to run without git rather than failing mysteriously later.
if ! command -v git >/dev/null 2>&1; then
  echo "FAIL: git is not installed or not on PATH." >&2
  exit 1
fi

workdir="$(mktemp -d "${TMPDIR:-/tmp}/day031-tests.XXXXXX")"
cleanup() { rm -rf "${workdir}"; }
trap cleanup EXIT
cd "${workdir}" || { echo "FAIL: could not enter temp dir" >&2; exit 1; }

echo "Testing branch/conflict/merge behavior in ${workdir} ..."

# --- Build the scenario ------------------------------------------------------
git init -q -b main
git config --local user.name "Day 31 Test"
git config --local user.email "test@example.invalid"

printf '%s\n' "# Pancakes" "flour: 1 cup" "milk: 1 cup" "eggs: 1" > recipe.txt
git add recipe.txt
git commit -q -m "base"

# Feature branch edits line 3.
git switch -q -c feature-x
printf '%s\n' "# Pancakes" "flour: 1 cup" "milk: 2 cups" "eggs: 1" > recipe.txt
git commit -q -am "feature edit"

# 1) A branch was created.
if git branch --format='%(refname:short)' | grep -qx "feature-x"; then
  check "a feature branch was created" "yes"
else
  check "a feature branch was created" "no"
fi

# Competing edit on main, same line.
git switch -q main
printf '%s\n' "# Pancakes" "flour: 1 cup" "milk: 1 cup buttermilk" "eggs: 1" > recipe.txt
git commit -q -am "main edit"

# 2) Merging produces a conflict (non-zero exit + markers in the file).
if git merge --no-edit feature-x >/dev/null 2>&1; then
  check "merging the divergent branches produced a conflict" "no"
else
  check "merging the divergent branches produced a conflict" "yes"
fi

if grep -qE '^(<<<<<<<|=======|>>>>>>>)' recipe.txt; then
  check "git wrote conflict markers into the file" "yes"
else
  check "git wrote conflict markers into the file" "no"
fi

# git records the file as unmerged (status code UU) mid-conflict.
if [ -n "$(git ls-files --unmerged)" ]; then
  check "git records the file as unmerged during the conflict" "yes"
else
  check "git records the file as unmerged during the conflict" "no"
fi

# --- Resolve ----------------------------------------------------------------
printf '%s\n' "# Pancakes" "flour: 1 cup" "milk: 2 cups buttermilk" "eggs: 1" > recipe.txt

# 3) No conflict markers remain after resolution.
if grep -qE '^(<<<<<<<|=======|>>>>>>>)' recipe.txt; then
  check "conflict markers removed after resolution" "no"
else
  check "conflict markers removed after resolution" "yes"
fi

git add recipe.txt
git commit --no-edit -q

# 4) Working tree is clean after committing the merge.
if [ -z "$(git status --porcelain)" ]; then
  check "repository is clean after resolving the merge" "yes"
else
  check "repository is clean after resolving the merge" "no"
fi

# 5) The tip commit is a real merge commit (exactly two parents).
parents="$(git cat-file -p HEAD | grep -c '^parent ')"
if [ "${parents}" -eq 2 ]; then
  check "the final commit is a merge commit (two parents)" "yes"
else
  check "the final commit is a merge commit (two parents)" "no"
fi

# git rev-list agrees there is a merge in history.
if [ "$(git rev-list --merges --count HEAD)" -ge 1 ]; then
  check "history contains at least one merge commit" "yes"
else
  check "history contains at least one merge commit" "no"
fi

# 6) The graph renders the merge diamond (a line containing |\).
if git log --graph --oneline | grep -q '|\\'; then
  check "git log --graph shows the merge diamond" "yes"
else
  check "git log --graph shows the merge diamond" "no"
fi

# 7) The reference example script also runs clean end to end.
if bash "${lab_dir}/examples/branch_merge.sh" >/dev/null 2>&1; then
  check "examples/branch_merge.sh runs end to end and exits 0" "yes"
else
  check "examples/branch_merge.sh runs end to end and exits 0" "no"
fi

echo
echo "${checks} checks, ${failures} failure(s)."
[ "${failures}" -eq 0 ]