Git Branching and Merging: Commands, Strategies and Examples

# io.thecodeforge — Branch Management

# ─────────────────────────────────────────────────────────────
# CREATE AND SWITCH
# ─────────────────────────────────────────────────────────────

# Modern syntax (Git 2.23+)
git switch -c feature/payment-retry
# Creates branch and switches to it.

# Legacy syntax (still widely used)
git checkout -b feature/payment-retry

# Create branch from a specific commit
git switch -c hotfix/critical-bug abc1234
# Branch starts from commit abc1234, not HEAD.

# ─────────────────────────────────────────────────────────────
# LIST AND INSPECT
# ─────────────────────────────────────────────────────────────

git branch          # local branches (current branch marked with *)
git branch -r       # remote-tracking branches
git branch -a       # all branches (local + remote)
git branch -v       # branches with last commit info
git branch --merged main  # branches already merged into main
git branch --no-merged main  # branches not yet merged into main

# Find branches containing a specific commit
git branch --contains abc1234
# Useful when you need to know which branch introduced a bug.

# ─────────────────────────────────────────────────────────────
# PUSH AND TRACK
# ─────────────────────────────────────────────────────────────

# First push: set upstream tracking
git push -u origin feature/payment-retry
# -u sets upstream so future 'git push' and 'git pull' work without arguments.

# Subsequent pushes (upstream already set)
git push
# Automatically pushes to origin/feature/payment-retry.

# Push all local branches
git push origin --all

# ─────────────────────────────────────────────────────────────
# DELETE AND CLEAN UP
# ─────────────────────────────────────────────────────────────

# Delete local branch (safe — refuses if unmerged changes exist)
git branch -d feature/payment-retry

# Force delete local branch (discards unmerged changes)
git branch -D feature/payment-retry

# Delete remote branch
git push origin --delete feature/payment-retry

# Prune stale remote-tracking references
git remote prune origin
# Removes references to remote branches that have been deleted.

# Auto-delete after merge (GitHub/GitLab setting)
# Most platforms delete the branch automatically after PR merge.
# This keeps the remote clean without manual intervention.

# ─────────────────────────────────────────────────────────────
# RENAME
# ─────────────────────────────────────────────────────────────

# Rename current branch
git branch -m new-name

# Rename a different branch
git branch -m old-name new-name

# io.thecodeforge — Merge vs Rebase

# ─────────────────────────────────────────────────────────────
# MERGE: Preserves exact history
# ─────────────────────────────────────────────────────────────

# Standard merge (fast-forward if possible, merge commit if diverged)
git checkout main
git merge feature/payment-retry

# Force merge commit even when fast-forward is possible
git merge --no-ff feature/payment-retry
# Creates a merge commit that groups all feature branch commits.
# Useful for traceability: git log --first-parent main shows
# only merge commits, giving a high-level integration timeline.

# Squash merge: collapse all feature commits into one
git merge --squash feature/payment-retry
git commit -m "feat(payment): Add PaymentRetryService"
# All changes from the feature branch are staged.
# You create a single commit on main with the combined changes.
# The feature branch's individual commit history is lost on main.

# ─────────────────────────────────────────────────────────────
# REBASE: Linearises history
# ─────────────────────────────────────────────────────────────

# Rebase feature branch onto latest main
git checkout feature/payment-retry
git rebase main
# Your commits are replayed on top of main's latest commit.
# Each commit gets a new SHA.
# Then fast-forward merge:
git checkout main
git merge feature/payment-retry  # fast-forward, linear history

# Interactive rebase: squash, reorder, edit commits before merging
git rebase -i main
# Editor opens with:
# pick a1b2c3d Add PaymentRetryService
# pick e4f5g6h Add retry config validation
# pick i7j8k9l Fix typo in RetryConfig
#
# Change to:
# pick a1b2c3d Add PaymentRetryService
# squash e4f5g6h Add retry config validation
# fixup i7j8k9l Fix typo in RetryConfig
#
# Result: one clean commit combining all three.

# ─────────────────────────────────────────────────────────────
# THE GOLDEN RULE
# ─────────────────────────────────────────────────────────────

# SAFE: rebase local-only branches (never pushed)
git rebase main  # on a branch only you use

# DANGEROUS: rebase pushed shared branches
git rebase main  # on develop, which 12 engineers pull from
# Then: git push --force  ← THIS BREAKS EVERYONE

# IF YOU MUST rewrite shared history:
# 1. Coordinate with the team first
# 2. Use --force-with-lease (never --force)
# 3. Have everyone fetch and reset after your push

# io.thecodeforge — Resolving Merge Conflicts

# ─────────────────────────────────────────────────────────────
# CONFLICT DURING MERGE
# ─────────────────────────────────────────────────────────────

git merge feature/payment-retry
# CONFLICT (content): Merge conflict in src/main/java/io/thecodeforge/payment/PaymentService.java
# Automatic merge failed; fix conflicts and then commit the result.

# Check which files have conflicts
git status
# Both modified: src/main/java/io/thecodeforge/payment/PaymentService.java

git diff --name-only --diff-filter=U
# Shows only files with unresolved conflicts.

# ─────────────────────────────────────────────────────────────
# CONFLICT MARKERS IN THE FILE
# ─────────────────────────────────────────────────────────────

# <<<<<<< HEAD (your current branch)
# public PaymentResult processPayment(Order order) {
#     return paymentClient.charge(order.getAmount(), order.getCurrency());
# =======
# public PaymentResult processPayment(Order order, boolean retryEnabled) {
#     if (retryEnabled) {
#         return retryService.chargeWithRetry(order);
#     }
#     return paymentClient.charge(order.getAmount(), order.getCurrency());
# }
# >>>>>>> feature/payment-retry

# Edit the file to produce the correct combined result:
# public PaymentResult processPayment(Order order, boolean retryEnabled) {
#     if (retryEnabled) {
#         return retryService.chargeWithRetry(order);
#     }
#     return paymentClient.charge(order.getAmount(), order.getCurrency());
# }

# ─────────────────────────────────────────────────────────────
# RESOLVE AND COMPLETE
# ─────────────────────────────────────────────────────────────

# Stage the resolved file
git add src/main/java/io/thecodeforge/payment/PaymentService.java

# Complete the merge
git commit
# Git auto-generates a merge commit message.
# Or provide your own:
git commit -m "Merge featuren
# ─────────────────────────/payment-retry: resolve PaymentService conflict"\────────────────────────────────────
# ABORT: If conflicts are too complex
# ─────────────────────────────────────────────────────────────

git merge --abort
# Cancels the merge. Working directory restored to pre-merge state.
# Safe to use at any point during conflict resolution.

# ─────────────────────────────────────────────────────────────
# CONFLICT DURING REBASE
# ─────────────────────────────────────────────────────────────

# If conflicts occur during rebase:
git rebase main
# CONFLICT (content): Merge conflict in PaymentService.java

# Resolve the conflict, then:
git add src/main/java/io/thecodeforge/payment/PaymentService.java
git rebase --continue
# Git moves to the next commit in the rebase sequence.
# More conflicts may occur in subsequent commits.

# Skip a commit during rebase (if it's not important):
git rebase --skip
# Discards the current commit's changes entirely.

# Abort the entire rebase:
git rebase --abort
# Returns to the state before the rebase started.

# ─────────────────────────────────────────────────────────────
# MERGE TOOLS
# ─────────────────────────────────────────────────────────────

# Configure a merge tool
git config --global merge.tool vimdiff
# Or: vscode, meld, p4merge, kdiff3, beyondcompare

# Launch merge tool for all conflicted files
git mergetool
# Opens the configured tool with three panes:
# LOCAL (your version), REMOTE (incoming version), BASE (common ancestor)

# io.thecodeforge — Fast-Forward vs 3-Way Merge

# ─────────────────────────────────────────────────────────────
# FAST-FORWARD: No divergence, pointer just moves forward
# ─────────────────────────────────────────────────────────────

# Scenario: main is at commit A. You branched feature from A.
# You made commits B and C on feature. main is still at A.
# No commits were added to main since you branched.

git checkout main
git merge feature/payment-retry
# Fast-forward
# Updating 8d1e3f5..a1b2c3d
# Fast-forward
#  src/main/java/io/thecodeforge/payment/PaymentRetryService.java | 87 +++

# Result: main now points to commit C. No merge commit created.
# git log shows: C → B → A (linear)

# Force a merge commit even with fast-forward
git merge --no-ff feature/payment-retry
# Result: Merge commit M with parents C and A.
# git log shows: M → C → B → A (with branch visible)

# ─────────────────────────────────────────────────────────────
# 3-WAY MERGE: Both branches diverged
# ─────────────────────────────────────────────────────────────

# Scenario: main is at commit A. You branched feature from A.
# You made B and C on feature. Meanwhile, someone added D on main.
# Both branches diverged from A.

git checkout main
git merge feature/payment-retry
# Merge made by the 'ort' strategy.
#  src/main/java/io/thecodeforge/payment/PaymentRetryService.java | 87 +++
#  1 file changed, 87 insertions(+)

# Result: Merge commit M with parents C (feature) and D (main).
# The merge base is A. Git computes: diff(A→C) + diff(A→D) and combines them.

# ─────────────────────────────────────────────────────────────
# VIEWING THE MERGE BASE
# ─────────────────────────────────────────────────────────────

git merge-base main feature/payment-retry
# Output: <sha-of-commit-A>
# This is the common ancestor used for the 3-way merge.

# ─────────────────────────────────────────────────────────────
# FIRST-PARENT LOG: See only merge commits on main
# ─────────────────────────────────────────────────────────────

git log --first-parent main --oneline
# Shows only commits on main's direct lineage.
# Merge commits appear, but individual feature commits don't.
# This gives a high-level integration timeline.
# Only works well if you use --no-ff merges.

# io.thecodeforge — Branch Strategies

# ─────────────────────────────────────────────────────────────
# GITFLOW
# ─────────────────────────────────────────────────────────────

# Branches: main, develop, feature/*, release/*, hotfix/*

# Start a feature
git checkout develop
git checkout -b feature/payment-retry

# Finish a feature: merge into develop
git checkout develop
git merge --no-ff feature/payment-retry
git branch -d feature/payment-retry

# Start a release
git checkout develop
git checkout -b release/v2.5.0
# Bug fixes only on release branch

# Finish a release: merge into main works well for continuous to main triggers a deploy. It deployment but requires AND develop
git checkout main
git merge --no-ff release/v2.5.0
git tag -a v2.5.0 -m "Release v2.5.0"
git checkout develop
git merge --no-ff release/v2.5.0
git branch -d release/v2.5.0

# Hotfix: branch from main, merge back to main AND develop
git checkout main
git checkout -b hotfix/critical-bug
# Fix the bug
git checkout main
git merge --no-ff hotfix/critical-bug
git tag -a v2.5.1 -m "Hotfix v2.5.1"
git checkout develop
git merge --no-ff hotfix/critical-bug

# ─────────────────────────────────────────────────────────────
# GITHUB FLOW
# ─────────────────────────────────────────────────────────────

# Branches: main, feature/* (short-lived)

# Create feature branch from main
git checkout main
git checkout -b feature/payment-retry

# Push and open PR
git push -u origin feature/payment-retry
# Open PR on GitHub. CI runs automatically.

# After PR approval: merge into main (or squash merge)
# GitHub merges the PR. Main is deployed automatically.

# Delete feature branch after merge
git branch -d feature/payment-retry

# ─────────────────────────────────────────────────────────────
# TRUNK-BASED DEVELOPMENT
# ─────────────────────────────────────────────────────────────

# Branches: main (trunk), very short-lived branches (hours)

# Create short-lived branch
git checkout -b feature/payment-retry

# Commit frequently (multiple times per day)
git add src/main/java/io/thecodeforge/payment/PaymentRetryService.java
git commit -m "WIP: PaymentRetryService skeleton"

# Rebase onto main before merging (to stay current)
git fetch origin
git rebase origin/main

# Merge into main via PR (or direct push with CI gates)
git checkout main
git merge --ff-only feature/payment-retry
# --ff-only ensures no merge commit. Linear history.

# Feature flags for incomplete work
# In application code:
# if (featureFlags.isEnabled("payment-retry")) {
#     return retryService.chargeWithRetry(order);
# }
# The feature is merged to main but hidden behind a flag.