Git Pull Explained: Fetch, Merge, and Avoid Team Chaos

# io.thecodeforge — DevOps tutorial

# ─────────────────────────────────────────────────────────────
# SCENARIO: You're on the 'main' branch of a team project.
# A colleague just pushed a bug fix to the remote repo.
# You need to get their changes before starting your next task.
# ─────────────────────────────────────────────────────────────

# Step 1: Check your current status before touching anything.
# Always do this. Know what state you're in before you pull.
git status
# Expected: 'nothing to commit, working tree clean'
# If you see modified files here — STOP. Stash or commit first.

# Step 2: See what branch you're on and where it sits vs. remote.
git log --oneline --decorate -5
# Shows the last 5 commits with branch pointers.
# Look for: HEAD -> main (your local) vs. origin/main (remote).
# If origin/main is ahead, you're behind — pull is needed.

# Step 3: Run fetch first to SEE what's coming, safely.
# This downloads remote changes but touches NOTHING in your working tree.
git fetch origin

# Step 4: Check what just arrived from the remote without merging yet.
# This shows commits on origin/main that aren't on your local main.
git log main..origin/main --oneline
# Output shows each incoming commit on its own line.
# If this is empty, you're already up to date.

# Step 5: Now merge the fetched changes into your local branch.
# This is the step that actually updates your files.
git merge origin/main

# ─── OR ────────────────────────────────────────────────────────
# Do both steps at once with git pull (only when working tree is clean).
git pull origin main
# Equivalent to: git fetch origin && git merge origin/main
# The 'origin' is the remote name. 'main' is the branch. Both are explicit here.
# Relying on defaults is fine locally but be explicit in scripts.

# io.thecodeforge — DevOps tutorial

# ─────────────────────────────────────────────────────────────
# SCENARIO: Mid-morning on the checkout-service team.
# You've been editing OrderValidator.java for 45 minutes.
# Your team lead just Slacked: "pushed the tax fix, pull when ready."
# Your working tree is NOT clean. Here's the safe workflow.
# ─────────────────────────────────────────────────────────────

# Step 1: Always check status first. Non-negotiable.
git status
# You see: 'modified: src/orders/OrderValidator.java'
# Do NOT pull yet.

# Step 2: Stash your in-progress changes.
# git stash is a stack — it saves your current diff and reverts the file.
# The message makes it identifiable when you have multiple stashes.
git stash push -m "WIP: adding discount threshold logic to OrderValidator"
# Output: Saved working directory and index state On main: WIP: adding...

# Step 3: Confirm working tree is now clean before pulling.
git status
# Output: 'nothing to commit, working tree clean' — safe to pull.

# Step 4: Pull the remote changes cleanly.
git pull origin main
# Output: Updating 9b1c233..e4f9021 — fast-forward or merge commit.

# Step 5: Re-apply your stashed work on top of the fresh code.
git stash pop
# Output: On branch main — your changes are restored on top of the new base.

# Step 6: Check if your work and the pulled changes conflict.
git status
# If OrderValidator.java shows 'both modified', you have a conflict to fix.
# If it shows 'modified' with no conflict markers — you're clean.

# ─────────────────────────────────────────────────────────────
# WHAT A CONFLICT LOOKS LIKE INSIDE OrderValidator.java:
# ─────────────────────────────────────────────────────────────
# <<<<<<< HEAD (your stashed changes after pop)
#   if (orderTotal > discountThreshold) {
# =======
#   if (orderTotal > 0 && taxRate != null) {  // team lead's tax fix
# >>>>>>> origin/main
#
# You must edit this file manually to combine both intentions,
# then run: git add src/orders/OrderValidator.java
# then run: git commit -m "Merge tax fix with discount threshold logic"
# ─────────────────────────────────────────────────────────────

# To see everything currently on the stash stack:
git stash list
# stash@{0}: On main: WIP: adding discount threshold logic to OrderValidator

# io.thecodeforge — DevOps tutorial

# ─────────────────────────────────────────────────────────────
# SCENARIO: You're working on the checkout-service feature branch.
# You've made 2 local commits (not pushed yet).
# The remote main has 3 new commits since you branched.
# Goal: get remote changes without polluting history with merge commits.
# ─────────────────────────────────────────────────────────────

# ── WITHOUT --rebase (default merge behaviour) ──────────────────
# Your history before pull:
# A - B - C (origin/main)
#          \
#           D - E (your local commits, not pushed yet)
#
# After: git pull origin main
# A - B - C --------- M (merge commit — clutters history)
#          \         /
#           D - E --/

# ── WITH --rebase ───────────────────────────────────────────────
# Your history before pull:
# A - B - C (origin/main)
#          \
#           D - E (your local commits)
#
# After: git pull --rebase origin main
# A - B - C - D' - E' (linear — D and E replayed on top of C)
# D' and E' are new SHAs but same changes — history reads cleanly.

# ─────────────────────────────────────────────────────────────
# Running it:
# ─────────────────────────────────────────────────────────────

# Check current state before pulling
git log --oneline -5
# Shows your 2 local commits on top

# Pull with rebase — safe because your commits are not yet on remote
git pull --rebase origin main

# If a rebase conflict occurs during the replay of your commits,
# Git pauses and shows you the conflict.
# Fix the file, stage it, then continue the rebase:
git add src/payments/CheckoutOrchestrator.java
git rebase --continue
# Do NOT run git commit here — rebase --continue does the commit for you.

# If the conflict is too messy and you want to abort and go back to where you started:
git rebase --abort
# This resets everything as if you never ran the rebase — clean escape hatch.

# ─────────────────────────────────────────────────────────────
# Make rebase the default for ALL future pulls (recommended):
# ─────────────────────────────────────────────────────────────
git config --global pull.rebase true
# Now every 'git pull' behaves like 'git pull --rebase' automatically.
# You can still override per-command with --no-rebase when you need a merge commit.

# io.thecodeforge — DevOps tutorial

# ─────────────────────────────────────────────────────────────
# SCENARIO: You pulled on the inventory-service repo and hit a
# merge conflict in ProductRepository.java. Here's the recovery.
# ─────────────────────────────────────────────────────────────

# Step 1: After the failed pull, check what's in conflict.
git status
# Look for: 'both modified: src/inventory/ProductRepository.java'
# These are the files you must resolve before anything else works.

# Step 2: Open the conflicted file. You'll see this inside it:
# <<<<<<< HEAD
#   public List<Product> findByWarehouse(String warehouseId) {
#       return repository.findAll(warehouseId, StockFilter.ACTIVE);
# =======
#   public List<Product> findByWarehouse(String warehouseId, boolean includeReserved) {
#       return repository.findAll(warehouseId, includeReserved ? StockFilter.ALL : StockFilter.ACTIVE);
# >>>>>>> origin/main
#
# You need to decide: does the final version need both signatures?
# In this case: the remote version is a non-breaking extension — keep it.
# Edit the file to the correct final state, remove ALL conflict markers.

# Step 3: After manually editing, stage the resolved file.
git add src/inventory/ProductRepository.java

# Step 4: If there are more conflicted files, resolve and stage them too.
# Check: git status — repeat Step 2-3 for each 'both modified' file.

# Step 5: Complete the merge commit.
git commit
# Git opens your editor with a pre-filled merge commit message.
# Accept it or edit to describe what you resolved and why.
# Save and close — merge is complete.

# ─────────────────────────────────────────────────────────────
# ABORT OPTION: If you're overwhelmed and want to undo the whole pull:
# ─────────────────────────────────────────────────────────────
git merge --abort
# Resets your branch to exactly the state before you ran git pull.
# Safe to run any time DURING a conflicted merge (not after commit).

# ─────────────────────────────────────────────────────────────
# SCENARIO 2: 'fatal: refusing to merge unrelated histories'
# Happens when local repo and remote repo were created separately.
# ─────────────────────────────────────────────────────────────
git pull origin main --allow-unrelated-histories
# This is a one-time escape hatch. Do NOT add this flag routinely.
# After merging, inspect git log carefully — the combined history
# will look bizarre. That's expected. It's safe as long as the code works.