git column

Internal formatter. Used by ls-files and friends.

🎯 What & why

Internal column formatter Git uses to lay out lists like branch, tag, status -s, and ls-files in tidy multi-column blocks. You rarely call it directly, but knowing it explains why those commands suddenly stop columnizing in pipes.

🧠 Mental model

A pure text reformatter: read lines on stdin, emit a column-packed layout on stdout, sized to the terminal width. The 'auto' mode is the default everywhere — it activates only on a TTY, which is why git branch | cat looks single-column.

🛠️ Synopsis

git column [--command=<name>] [--mode=<mode>] [--raw-mode=<n>]
           [--width=<width>] [--indent=<string>] [--nl=<string>]
           [--padding=<n>]

Reads lines from stdin and writes a columnar layout to stdout.
--command=<name> lets it consult column.<name> / column.ui config so
callers like 'git branch' get consistent behavior. Most users meet it
indirectly via the column.ui or column.<command> settings.

🎚️ Switches & options

Flag	What it does
`--mode=<mode>`	Layout choice: 'always' (force columns), 'auto' (only on TTY), 'never'/'plain' (one per line), plus 'column' (fill columns first), 'row' (fill rows first), 'dense'/'nodense' (variable vs. fixed column widths).
`--raw-mode=<n>`	Set the layout mode by integer bitmask instead of a name. For scripts that already speak Git's internal flag values; prefer --mode for sanity.
`--width=<n>`	Override terminal width. Defaults to COLUMNS, then ioctl, then 80. Useful when piping for a known target (e.g., a fixed-width log).
`--indent=<str>`	String prepended to each output line. Handy for embedding columnized output under a heading.
`--nl=<str>`	String appended to each line in place of a plain newline. Lets you stitch the output into other formats.
`--padding=<n>`	Spaces between columns. Default 1; bump it when entries are visually dense.

💡 Use cases

Force git branch to columnize even when redirected, by setting column.branch=always.
Turn off columns globally in a CI log where it just confuses grep, with column.ui=never.
Reformat any newline-delimited list (not necessarily Git output) into terminal-fitted columns from a script.
Build pretty status displays in shell wrappers without reinventing column-packing math.

🧪 Examples

Columnize stdin in dense mode

ls | git column --mode=dense

Force a 120-col layout

git ls-files | git column --mode=always --width=120

Add an indent

git tag | git column --mode=always --indent='    '

Configure git branch to always columnize

git config --global column.branch always

🎓 Recommendations

Set column.ui=auto (the default) and override per-command via column.branch, column.tag, column.status only where you have a real preference.
Use 'dense' when your entries vary wildly in length — it packs much tighter than the fixed-width default.
Don't rely on column output as a parseable format. If you want to script over it, use --mode=plain or strip columns out of the equation entirely.

🪤 Common pitfalls

'auto' disables columns the moment output isn't a TTY — debugging 'why does my pipe look different?' usually ends here.
--width is the layout width; it doesn't truncate long entries. A single long line can push everything into one column.
Mixing --indent with --width is easy to get wrong: indent eats from the same budget, so set width accordingly.

🔗 Related modules

📝 Quiz

Hit each option, then Check answers. Score is recorded; Next is always open.