Introduction

Since Git 2.16, git branch pipes its output through a pager (typically less) when the output exceeds the terminal height. This means the branch list opens in an interactive scrollable view instead of printing directly to the terminal. To disable this behavior, set git config --global pager.branch false or set the GIT_PAGER environment variable. This change catches many developers off guard, especially when scripting.

Why This Happens

Git 2.16 (released January 2018) changed git branch to use the pager by default. Previously, branch output was printed directly to stdout. The change was made for consistency with other Git commands like git log and git diff, which have always used a pager.

The pager is triggered when:

• The output is going to a terminal (not piped or redirected)
• The output exceeds the terminal height
• A pager is configured (default: less)

1# These open the pager (output goes to terminal)
2git branch
3git branch -a
4git branch -r
5
6# These do NOT open the pager (output is piped/redirected)
7git branch | cat
8git branch > branches.txt
9git branch | grep feature

Fix 1: Disable Pager for git branch Only

1# Disable pager for git branch specifically
2git config --global pager.branch false
3
4# Verify
5git config --global --get pager.branch
6# false

This is the most targeted fix — other commands like git log and git diff still use the pager.

Fix 2: Use --no-pager Flag

1# One-time: skip the pager for this command
2git --no-pager branch
3git --no-pager branch -a
4
5# Alias it
6git config --global alias.br '!git --no-pager branch'
7
8# Now use: git br

Fix 3: Change the Pager Program

1# Use 'cat' as the pager (effectively disables paging)
2git config --global pager.branch cat
3
4# Use 'less' with specific options
5git config --global pager.branch 'less -FRX'
6# -F: quit if output fits on one screen
7# -R: show raw ANSI colors
8# -X: don't clear screen on exit

The -F flag is particularly useful — it makes less behave like cat when the output fits on one screen, but still pages for long output.

Fix 4: Disable Pager Globally

1# Disable pager for ALL git commands
2git config --global core.pager cat
3
4# Or via environment variable
5export GIT_PAGER=cat
6
7# Or disable completely
8git config --global core.pager ''

This affects git log, git diff, git branch, and all other commands that use the pager.

Fix 5: Configure less Globally

1# Set default less options via environment variable
2export LESS='-FRX'
3
4# Add to ~/.bashrc or ~/.zshrc
5echo 'export LESS="-FRX"' >> ~/.bashrc
6
7# -F: quit automatically if output fits on screen
8# -R: allow ANSI color codes
9# -X: don't clear the screen when less exits
10# -S: chop long lines instead of wrapping

With LESS='-FRX', the pager exits automatically for short output and preserves the output on screen after quitting.

Navigating less (When You Want the Pager)

When the pager is useful (long branch lists), these keys help:

1Navigation:
2  j / Down Arrow   — scroll down one line
3  k / Up Arrow     — scroll up one line
4  Space / Page Down — scroll down one page
5  b / Page Up       — scroll up one page
6  g                 — go to beginning
7  G                 — go to end
8
9Searching:
10  /pattern          — search forward
11  ?pattern          — search backward
12  n                 — next match
13  N                 — previous match
14
15Exiting:
16  q                 — quit

Git Config Pager Precedence

Git determines the pager in this order (highest priority first):

1. GIT_PAGER environment variable
2. core.pager git config
3. PAGER environment variable
4. Default: less

Per-command settings (pager.branch, pager.log, etc.) override core.pager for that specific command.

1# Check what pager Git is using
2git var GIT_PAGER
3# less
4
5# Check per-command settings
6git config --get pager.branch
7git config --get pager.log
8git config --get pager.diff

Scripting with Git Branch

In scripts, the pager can cause hangs because less waits for keyboard input:

1#!/bin/bash
2
3# BAD — may open pager and hang the script
4branches=$(git branch)
5
6# GOOD — --no-pager prevents interactive pager
7branches=$(git --no-pager branch)
8
9# GOOD — piping disables the pager automatically
10branches=$(git branch | cat)
11
12# GOOD — GIT_PAGER=cat for the duration of the script
13export GIT_PAGER=cat
14branches=$(git branch)
15
16# Best practice for scripts: use plumbing commands
17branches=$(git for-each-ref --format='%(refname:short)' refs/heads/)

Common Pitfalls

• Scripts hanging on git branch: When git branch is called in a script without redirection, it opens less and waits for input, causing the script to hang. Always use git --no-pager branch or pipe the output (git branch | cat) in scripts.
• Setting core.pager to empty string disables colors: Setting git config core.pager '' disables the pager but also loses color output because Git only emits ANSI colors when outputting to a pager. Use core.pager cat instead to preserve colors.
• Forgetting --global scope: git config pager.branch false without --global only applies to the current repository. Other clones still use the pager. Use --global for user-wide settings or --system for machine-wide.
• LESS environment variable conflicting with Git: If LESS is set to options that disable raw mode (e.g., without -R), Git's colored output shows raw escape codes instead of colors. Always include -R in your LESS variable.
• Expecting git branch output to be stable for parsing: The output format of git branch varies between Git versions and includes decorations (like * main for the current branch). For scripts, use git for-each-ref or git branch --format='%(refname:short)' for stable, parseable output.

Summary

• Git 2.16+ pipes git branch output through a pager (less) by default
• Disable with git config --global pager.branch false for branch only
• Use git --no-pager branch for one-time pager bypass
• Set LESS='-FRX' so less exits automatically for short output and preserves screen content
• In scripts, always use git --no-pager or pipe output to avoid hanging on interactive pager input
• Use git for-each-ref instead of git branch in scripts for stable, parseable output