show-branch Git Command Guide

The git show-branch command displays a textual representation of the commit topology and branch relationships in a repository. It shows how branches relate to each other and helps visualize the commit history structure, making it useful for understanding complex branch topologies and merge relationships.

git show-branch Syntax:

git show-branch [<options>] [<rev> | <glob>]...
git show-branch (--all | --remotes | --topo-order | --date-order)
                 [--current] [--color[=<when>] | --no-color] [--sparse]
                 [--more=<n> | --list | --independent | --merge-base]
                 [--no-name | --sha1-name] [--topics]
                 [(<rev> | <glob>)...]

Display Control Options:

Option	Description
--all	Show all refs under refs/
--remotes	Show remote-tracking branches
--current	Include current branch
--color[=<when>]	Color output control
--no-color	Disable color output
--sparse	Suppress commits not on all branches
--more=<n>	Show additional commits
--list	Synonym for —more=-1
--merge-base	List merge bases for the given commits
--independent	List refs with no common commits
--no-name	Don’t show ref names
--sha1-name	Name commits with unique prefix of SHA-1

Ordering Options:

Option	Description
--topo-order	Show commits in topological order
--date-order	Show commits in date order
--topics	Show only commits not on the first branch

Output Control Options:

Option	Description
-g, --reflog	Show reflog information
--decorate[=<format>]	Decorate refs with additional info

Parameters:

Parameter	Description
<rev>	Commit or branch reference
<glob>	Glob pattern for refs

Understanding Show-Branch Output:

Basic Output Structure:

Branch Topology Display:
* [branch-name] commit subject
 ! [other-branch] commit subject
  ! [third-branch] commit subject
---
  +  [branch-name] commit subject
  +  [branch-name^] parent commit
 ++ [other-branch] commit subject

Column Markers:

Column Markers:
├── * = Commit is on the current branch
├── + = Commit is on this branch
├── - = Commit is not on this branch
├── ! = Branch reference point
└── [name] = Branch name or commit reference

Branch Relationship Examples:

Simple Branch Structure:
* [main] Latest commit on main
 ! [feature] Latest commit on feature
--
*  [main] Merge commit
*  [main^] Commit before merge
 + [feature] Feature commit
 + [feature^] Base commit

Complex Merge Structure:
* [main] Recent main commit
 ! [feature-a] Feature A head
  ! [feature-b] Feature B head
---
  * [main] Merge of A and B
  + [feature-a] Feature A changes
  + [feature-b] Feature B changes
  * [main^] Common ancestor

Basic Show-Branch Operations:

Branch Topology Visualization:

# Show current branch topology
git show-branch

# Show specific branches
git show-branch main feature-branch

# Show multiple branches
git show-branch main develop feature-1 feature-2

# Show all branches
git show-branch --all

# Show remote branches
git show-branch --remotes

Commit History Analysis:

# Show recent commit history
git show-branch --more=10

# Show all commits (no limit)
git show-branch --list

# Show commits in date order
git show-branch --date-order

# Show commits in topological order
git show-branch --topo-order

Branch Relationship Analysis:

# Find merge bases
git show-branch --merge-base main feature

# Show independent branches
git show-branch --independent main feature bugfix

# Show branch divergence
git show-branch main..feature

Advanced Show-Branch Scenarios:

Complex Repository Analysis:

# Analyze release branches
git show-branch v1.0 v1.1 v2.0 main

# Compare feature branches
git show-branch --topics feature-* main

# Analyze hotfix branches
git show-branch --remotes origin/hotfix-* origin/main

# Show branch creation points
git show-branch --merge-base --all

Reflog Integration:

# Show reflog information
git show-branch -g

# Show reflog for specific branches
git show-branch -g main feature

# Analyze branch history
git show-branch --reflog --all | head -20

Custom Branch Selection:

# Use glob patterns
git show-branch 'refs/heads/feature/*'

# Show specific remote branches
git show-branch 'refs/remotes/origin/*'

# Combine local and remote
git show-branch main origin/main

Sparse Display:

# Show only common commits
git show-branch --sparse main feature

# Limit output depth
git show-branch --more=5 main develop

# Focus on recent activity
git show-branch --more=3 --current

Configuration and Best Practices:

Git Configuration for Show-Branch:

# Configure show-branch behavior
git config showbranch.default "main develop"  # Default branches to show

# Configure colors
git config color.showbranch.current yellow
git config color.showbranch.local green
git config color.showbranch.remote red

# Configure output format
git config showbranch.defaultFormat "%h %s %d"

Show-Branch Best Practices:

# Use for branch analysis
git show-branch --all | head -20

# Check merge relationships
git show-branch --merge-base feature main

# Analyze complex topologies
git show-branch --topo-order --all

# Regular repository inspection
git show-branch --current --remotes

Safe Show-Branch Operations:

# Check repository state first
git status

# Limit output for large repos
git show-branch --more=5 --all

# Use specific branches
git show-branch main develop  # Instead of --all

Integration with Development Workflows:

Branch Strategy Analysis:

#!/bin/bash
# Analyze branch strategy with show-branch

analyze_branches() {
    echo "=== Branch Strategy Analysis ==="

    # Show current branch topology
    echo "Current branch topology:"
    git show-branch --current --remotes | head -15

    # Analyze branch relationships
    echo ""
    echo "Branch relationships:"
    git show-branch --merge-base --all 2>/dev/null | while read -r line; do
        echo "Merge base: $line"
    done

    # Check for complex merges
    echo ""
    echo "Complex merge analysis:"
    git log --oneline --graph --all | head -20

    # Branch age analysis
    echo ""
    echo "Branch age analysis:"
    git for-each-ref --sort=-committerdate refs/heads/ --format='%(refname:short) %(committerdate:relative)' | head -10

    echo "Analysis complete"
}

analyze_branches

Merge Planning:

# Plan merges using show-branch
plan_merge() {
    local source_branch="$1"
    local target_branch="${2:-main}"

    echo "=== Merge Planning: $source_branch -> $target_branch ==="

    # Show branch relationship
    echo "Branch relationship:"
    git show-branch "$target_branch" "$source_branch" | head -10

    # Find merge base
    echo ""
    echo "Merge base:"
    git show-branch --merge-base "$target_branch" "$source_branch"

    # Check for conflicts ahead
    echo ""
    echo "Potential conflicts:"
    git diff --name-only "$target_branch...$source_branch" | head -10

    # Show recent commits on source
    echo ""
    echo "Recent commits on $source_branch:"
    git log --oneline "$source_branch" --not "$target_branch" | head -5

    echo "Merge planning complete"
}

plan_merge "feature/new-api" "develop"

Repository Health Check:

# Repository health check with show-branch
health_check() {
    echo "=== Repository Health Check ==="

    # Check branch topology
    echo "Branch topology health:"
    if git show-branch --all >/dev/null 2>&1; then
        echo "✓ Branch topology is valid"
    else
        echo "⚠ Branch topology issues detected"
    fi

    # Check for orphaned branches
    echo ""
    echo "Orphaned branch check:"
    git show-branch --independent --all 2>/dev/null | while read -r branch; do
        echo "Independent branch: $branch"
    done

    # Check merge base validity
    echo ""
    echo "Merge base validation:"
    git show-branch --merge-base --all >/dev/null 2>&1 && echo "✓ Merge bases valid" || echo "⚠ Merge base issues"

    # Check reflog health
    echo ""
    echo "Reflog health:"
    git show-branch -g >/dev/null 2>&1 && echo "✓ Reflog accessible" || echo "⚠ Reflog issues"

    echo "Health check complete"
}

health_check

Troubleshooting Common Issues:

Complex Output Issues:

# Simplify complex output
git show-branch --sparse main feature

# Limit output depth
git show-branch --more=3 main develop feature

# Use specific branches
git show-branch main origin/main  # Instead of --all

Performance Issues:

# Speed up large repository analysis
git show-branch --more=5 --current

# Use specific refs
git show-branch main develop  # Limit scope

# Avoid expensive operations
git show-branch --no-color --current  # Reduce formatting

Display Issues:

# Fix color problems
git show-branch --color=always | cat

# Handle terminal width
COLUMNS=120 git show-branch

# Fix encoding issues
git show-branch --encoding=UTF-8

Branch Reference Issues:

# Fix invalid branch references
git show-branch --all 2>/dev/null || echo "Some branches invalid"

# Check branch existence
git show-ref | grep "refs/heads/"

# Validate remote branches
git ls-remote origin 2>/dev/null | head -5

Merge Base Issues:

# Handle missing merge bases
git show-branch --merge-base main feature 2>/dev/null || echo "No common history"

# Check repository connectivity
git fsck --unreachable | grep commit | wc -l

# Validate commit objects
git cat-file -t HEAD

Reflog Issues:

# Handle reflog problems
git show-branch -g 2>/dev/null || echo "Reflog issues"

# Check reflog size
git reflog | wc -l

# Clean old reflog entries
git reflog expire --all

Caution

git show-branch can produce complex output in repositories with many branches. Use —more to limit output. Some options may be slow on large repositories.

Real-World Usage Examples:

Development Workflow Integration:

#!/bin/bash
# Development workflow with show-branch

dev_workflow_branch() {
    echo "=== Development Branch Analysis ==="

    # Show current development state
    echo "Current branch topology:"
    git show-branch --current --remotes | head -15

    # Analyze active feature branches
    echo ""
    echo "Active feature branches:"
    git branch -r | grep "origin/feature" | while read -r branch; do
        branch_name=$(basename "$branch")
        commits_ahead=$(git rev-list --count "origin/main..$branch")
        last_commit=$(git log -1 --format="%ci %s" "$branch")
        echo "$branch_name: $commits_ahead commits ahead, last: $last_commit"
    done

    # Check merge readiness
    echo ""
    echo "Merge readiness check:"
    git branch -r | grep "origin/feature" | while read -r branch; do
        branch_name=$(basename "$branch")
        if git diff --quiet "$branch" "origin/main"; then
            echo "$branch_name: ✓ Ready to merge"
        else
            conflicts=$(git diff --name-only "$branch" "origin/main" | wc -l)
            echo "$branch_name: ⚠ $conflicts files differ"
        fi
    done

    # Show recent branch activity
    echo ""
    echo "Recent branch activity:"
    git reflog --since="1 week ago" | grep "checkout:" | head -10

    echo "Branch analysis complete"
}

dev_workflow_branch

Release Management:

# Release branch management with show-branch
release_management() {
    echo "=== Release Management Analysis ==="

    # Show release branch topology
    echo "Release branch topology:"
    git show-branch --remotes | grep -E "(release|tag)" | head -10

    # Analyze release stability
    echo ""
    echo "Release stability analysis:"
    git tag --list | tail -5 | while read -r tag; do
        # Check if tag is on main branch
        if git merge-base --is-ancestor "$tag" main 2>/dev/null; then
            echo "$tag: ✓ On main branch"
        else
            echo "$tag: ⚠ Not on main branch"
        fi
    done

    # Check release branch merges
    echo ""
    echo "Release branch merge analysis:"
    git log --oneline --merges --grep="release" | head -5

    # Show upcoming releases
    echo ""
    echo "Upcoming release branches:"
    git branch -r | grep "origin/release" | while read -r branch; do
        branch_name=$(basename "$branch")
        commits=$(git rev-list --count "$branch")
        last_update=$(git log -1 --format="%ci" "$branch")
        echo "$branch_name: $commits commits, last update: $last_update"
    done

    # Release timeline
    echo ""
    echo "Release timeline:"
    git tag --format="%(creatordate:short) %(refname:short)" | sort -r | head -10

    echo "Release management analysis complete"
}

release_management

Code Review Workflow:

# Code review workflow with show-branch
code_review_workflow() {
    echo "=== Code Review Branch Analysis ==="

    # Show review branch topology
    echo "Review branch topology:"
    git show-branch --all | grep -E "(review|pr|pull)" | head -10

    # Analyze pull request branches
    echo ""
    echo "Pull request analysis:"
    git branch -r | grep -E "(pr|pull|review)" | while read -r branch; do
        branch_name=$(basename "$branch")
        commits=$(git rev-list --count "origin/main..$branch")
        authors=$(git shortlog -s -n "origin/main..$branch" | wc -l)
        files_changed=$(git diff --name-only "origin/main..$branch" | wc -l)

        echo "$branch_name:"
        echo "  Commits: $commits"
        echo "  Authors: $authors"
        echo "  Files changed: $files_changed"

        # Check review status (simplified)
        if git log --grep="Reviewed-by:" "origin/main..$branch" | grep -q .; then
            echo "  Status: ✓ Reviewed"
        else
            echo "  Status: ⏳ Awaiting review"
        fi
        echo ""
    done

    # Show merge conflicts risk
    echo "Merge conflict risk assessment:"
    git branch -r | grep -E "(pr|pull|review)" | while read -r branch; do
        branch_name=$(basename "$branch")
        common_files=$(git diff --name-only "origin/main...$branch" | wc -l)
        echo "$branch_name: $common_files files may conflict"
    done

    echo "Code review analysis complete"
}

code_review_workflow

Repository Archaeology:

# Repository archaeology with show-branch
repository_archaeology() {
    echo "=== Repository Archaeology ==="

    # Show ancient branch topology
    echo "Ancient branch topology:"
    git show-branch --all --more=50 | tail -20

    # Find branch creation points
    echo ""
    echo "Branch creation analysis:"
    git for-each-ref --format='%(refname:short) %(creatordate:relative)' refs/heads/ | sort -k2 -n | head -10

    # Analyze merge patterns over time
    echo ""
    echo "Merge pattern evolution:"
    for year in {2020..2024}; do
        merges=$(git log --oneline --merges --since="$year-01-01" --until="$year-12-31" | wc -l)
        echo "$year: $merges merge commits"
    done

    # Find long-lived branches
    echo ""
    echo "Long-lived branches:"
    git for-each-ref --sort=-committerdate --format='%(refname:short) %(committerdate:relative)' refs/heads/ | awk '$2 ~ /(year|month)/ {print}' | head -5

    # Analyze branch naming evolution
    echo ""
    echo "Branch naming patterns over time:"
    git log --all --format='%ci %D' | grep -o 'origin/[^,)]*' | sort | uniq -c | sort -nr | head -10

    # Find resurrected branches
    echo ""
    echo "Branch resurrection analysis:"
    git reflog --all | grep "checkout:" | awk '{print $8}' | sort | uniq -c | sort -nr | head -5

    echo "Repository archaeology complete"
}

repository_archaeology

Team Collaboration Analysis:

# Team collaboration analysis with show-branch
team_collaboration_analysis() {
    echo "=== Team Collaboration Analysis ==="

    # Show team branch interactions
    echo "Team branch interactions:"
    git show-branch --all --more=20 | grep -E "(\[|\+|\-)" | head -15

    # Analyze cross-team merges
    echo ""
    echo "Cross-team merge analysis:"
    git log --oneline --merges --all | while read -r line; do
        hash=$(echo "$line" | cut -d' ' -f1)
        parents=$(git show --no-patch --format="%P" "$hash")
        parent1_author=$(git show --no-patch --format="%an" "${parents%% *}")
        parent2_author=$(git show --no-patch --format="%an" "${parents##* }")

        # Check if different teams (simplified)
        if [[ "$parent1_author" != "$parent2_author" ]]; then
            echo "Cross-team merge: $line"
            echo "  Authors: $parent1_author, $parent2_author"
        fi
    done | head -5

    # Show collaboration hotspots
    echo ""
    echo "Collaboration hotspots (frequently co-authored files):"
    git log --name-only --all | grep -v "^$" | sort | uniq -c | sort -nr | head -10

    # Analyze pair programming
    echo ""
    echo "Pair programming analysis:"
    git log --all --grep="Co-authored-by:" --oneline | wc -l
    echo " commits with co-authors"

    # Show team branch ownership
    echo ""
    echo "Team branch ownership:"
    git for-each-ref --format='%(refname:short) %(authorname)' refs/heads/ | while read -r branch author; do
        # Categorize by team (simplified)
        if [[ "$author" == *"frontend"* ]] || [[ "$author" == *"ui"* ]]; then
            team="Frontend"
        elif [[ "$author" == *"backend"* ]] || [[ "$author" == *"api"* ]]; then
            team="Backend"
        else
            team="Other"
        fi
        echo "$branch: $team team ($author)"
    done | sort -k2 | head -10

    echo "Team collaboration analysis complete"
}

team_collaboration_analysis

Automated Repository Monitoring:

# Automated repository monitoring with show-branch
repository_monitoring() {
    echo "=== Automated Repository Monitoring ==="

    # Monitor branch health
    echo "Branch health monitoring:"
    total_branches=$(git branch -a | wc -l)
    active_branches=$(git branch -r | wc -l)
    stale_branches=$(git branch -v | awk '$3 ~ /[0-9]+ (month|year)/ {count++} END {print count+0}')

    echo "Total branches: $total_branches"
    echo "Active branches: $active_branches"
    echo "Potentially stale: $stale_branches"

    # Monitor merge activity
    echo ""
    echo "Merge activity monitoring:"
    recent_merges=$(git log --oneline --merges --since="1 week ago" | wc -l)
    echo "Merges this week: $recent_merges"

    # Monitor branch topology complexity
    echo ""
    echo "Branch topology complexity:"
    topology_lines=$(git show-branch --all 2>/dev/null | wc -l)
    if [ "$topology_lines" -gt 100 ]; then
        echo "⚠ Complex branch topology ($topology_lines lines)"
    else
        echo "✓ Manageable branch topology"
    fi

    # Monitor for problematic branches
    echo ""
    echo "Problematic branch detection:"
    git branch -v | while read -r branch commit rest; do
        branch=$(echo "$branch" | sed 's/^* //')
        # Check for very old branches
        if git log -1 --since="1 year ago" "$commit" >/dev/null 2>&1; then
            continue
        else
            echo "Very old branch: $branch"
        fi
    done | head -3

    # Generate monitoring report
    cat > "repo-monitor-$(date +%Y%m%d).txt" << EOF
Repository Monitoring Report - $(date)

Branch Statistics:
- Total branches: $total_branches
- Active branches: $active_branches
- Stale branches: $stale_branches

Activity Metrics:
- Merges this week: $recent_merges
- Topology complexity: $topology_lines lines

Health Status: $([ "$stale_branches" -gt 5 ] && echo "⚠ Attention needed" || echo "✓ Healthy")
EOF

    echo "✓ Monitoring report generated: repo-monitor-$(date +%Y%m%d).txt"
}

repository_monitoring

Tip

Use git show-branch —all to see complete repository topology. Combine with —more to limit output depth. Use —merge-base to understand branch relationships.

What’s the difference between git show-branch and git log —graph?

git show-branch shows branch topology with column-based layout, while git log —graph shows commit graph with ASCII art. show-branch is better for branch relationships, log —graph for commit flow.

How do I see all branches in a compact format?

Use git show-branch —all —list to show all branches without topology details.

Can git show-branch show remote branches?

Yes, use git show-branch —remotes or specify remote branches explicitly.

How do I limit the output depth?

Use —more= to show additional commits beyond the default. Use —list for unlimited output.

What’s the —merge-base option for?

—merge-base shows the common ancestor commits between specified branches, useful for understanding where branches diverged.

Can git show-branch work with tags?

Yes, you can include tags in the branch list: git show-branch main v1.0 v2.0

How do I see only the current branch topology?

Use git show-branch —current to focus on the current branch and its relationships.

What’s the —independent option for?

—independent shows branches that have no commits in common, useful for finding completely separate development lines.

Can git show-branch show reflog information?

Yes, use -g or —reflog to include reflog entries in the branch topology display.

How do I see branches in date order?

Use git show-branch —date-order to show commits sorted by commit date rather than topology.

What’s the —topics option for?

—topics shows only commits that are not on the first specified branch, useful for seeing what other branches contribute.

Can git show-branch handle very large repositories?

Yes, but use limiting options like —more=5 and avoid —all on repositories with hundreds of branches.

How do I see branch creation dates?

Use git for-each-ref with show-branch, or check reflog for branch creation events.

What’s the —sparse option for?

—sparse suppresses commits that are not reachable from all specified branches, showing only the common history.

Can git show-branch work with glob patterns?

Yes, use glob patterns like ‘refs/heads/feature/*’ to match multiple branches.

How do I see the branch hierarchy?

The column-based output shows the hierarchy naturally, with * marking current branch and + showing branch membership.

What’s the performance impact of show-branch?

Generally fast, but —all on large repos with many branches can be slow. Use specific branch names instead.

Can show-branch detect merge conflicts?

No, it shows topology. Use git diff or git merge —no-commit to detect conflicts.

How do I see branches that need merging?

Compare outputs of git show-branch with and without —merge-base to identify branches that have diverged.

Applications of the git show-branch command

1. Branch Topology Analysis: Understanding complex branch relationships and merge histories
2. Merge Planning: Identifying merge bases and potential conflict areas
3. Repository Archaeology: Exploring historical branch structures and development patterns
4. Release Management: Analyzing release branch relationships and stability
5. Code Review: Understanding branch divergence and integration points
6. Team Coordination: Visualizing collaborative development workflows
7. Repository Maintenance: Identifying stale branches and cleanup opportunities
8. Development Strategy: Planning branch management and merge strategies