Where can I find info about the syntax of column.status?

Question

From the Git documentation about the git status command:

--column[=< options>]
--no-column
Display untracked files in columns. See configuration variable column.status for option syntax. --column and --no-column without options are equivalent to always and never respectively.

I can't see the option's syntax, because the git config column.status returns nothing. Where can I find info about this syntax? The git help status command shows the same info.

Answer 1

Besides the syntax of --column, you have a bug which has been fixed in Git 2.18 (Q2 2018), and illustrate again its syntax.

The code did not propagate the terminal width to subprocesses via COLUMNS environment variable, which it now does.
This caused trouble to "git column" helper subprocess when "git tag --column=row" tried to list the existing tags on a display with non-default width.

See commit b5d5a56 (11 May 2018) by Nguyễn Thái Ngọc Duy (pclouds).
See commit be11f7a (11 May 2018) by Jeff King (peff).
^{(Merged by Junio C Hamano -- gitster -- in commit 05682ee, 23 May 2018)}

column: fix off-by-one default width

By default we want to fill the whole screen if possible, but we do not want to use up all terminal columns because the last character is going hit the border, push the cursor over and wrap.
Keep it at the default value zero, which will make print_columns() set the width at term_columns() - 1.

pager: set COLUMNS to term_columns()

After we invoke the pager, our stdout goes to a pipe, not the terminal, meaning we can no longer use an ioctl to get the terminal width.
For that reason, ad6c373 (pager: find out the terminal width before spawning the pager, 2012-02-12, Git 1.7.9.2) started caching the terminal width.

But that cache is only an in-process variable.
Any programs we spawn will also not be able to run that ioctl, but won't have access to our cache. They'll end up falling back to our 80-column default.

You can see the problem with:

git tag --column=row

Since git-tag spawns a pager these days, its spawned git-column helper will see neither the terminal on stdout nor a useful COLUMNS value (assuming you do not export it from your shell already).
And you'll end up with 80-column output in the pager, regardless of your terminal size.

We can fix this by setting COLUMNS right before spawning the pager. That fixes this case, as well as any more complicated ones (e.g., a paged program spawns another script which then generates columnized output).

---

The parser for the "--nl" option of "git column"^(man) has been corrected with Git 2.34 (Q4 2021).

See commit c93ca46 (18 Aug 2021) by SZEDER Gábor (szeder).
^{(Merged by Junio C Hamano -- gitster -- in commit cfba196, 08 Sep 2021)}

column: fix parsing of the '--nl' option

^{Signed-off-by: SZEDER Gábor}

'git column'^(man)s '--nl' option can be used to specify a "string to be printed at the end of each line" (quoting the man page), but this option and its mandatory argument has been parsed as OPT_INTEGER since the introduction of the command in 7e29b82 ("Add column layout skeleton and git-column", 2012-04-21, Git v1.7.11-rc0 -- merge listed in batch #9).
Consequently, any non-number argument is rejected by parse-options, and any number other than 0 leads to segfault:

$ printf "%s\n" one two |git column --mode=plain --nl=foo
error: option `nl' expects a numerical value
$ printf "%s\n" one two |git column --mode=plain --nl=42
Segmentation fault (core dumped)
$ printf "%s\n" one two |git column --mode=plain --nl=0
one
two

Parse this option as OPT_STRING.

git column now includes in its man page:

--nl=<string>

---

With Git 2.45 (Q2 2024), batch 1, "git column"^(man) has been taught to reject negative padding value, as it would lead to nonsense behavior including division by zero.

See commit 76fb807, commit f2d31c6 (13 Feb 2024) by Kristoffer Haugsbakk (LemmingAvalanche).
^{(Merged by Junio C Hamano -- gitster -- in commit cf258a9, 26 Feb 2024)}

column: guard against negative padding

^{Suggested-by: Rubén Justo
Signed-off-by: Kristoffer Haugsbakk}

Make sure that client code can't pass in a negative padding by accident.

This will fail:

git column --mode=column --padding=-1

---

"git tag --column"^(man) failed to check the exit status of its git column^(man) invocation, which has been corrected with Git 2.45 (Q2 2024), batch 2.

See commit 92e6647 (14 Feb 2024) by Rubén Justo (rjusto).
^{(Merged by Junio C Hamano -- gitster -- in commit 9879386, 27 Feb 2024)}

tag: error when git-column fails

^{Signed-off-by: Rubén Justo}

If the user asks for the list of tags to be displayed in columns ("--columns"), a child git-column^(man) process is used to format the output as expected.

In a rare situation where we encounter a problem spawning that child process, we will work erroneously.

Make noticeable we're having a problem executing git-column, so the user can act accordingly.

The error message will be:

could not start 'git column'

---

Examples from the documentation

Those are what I looked at. To me, I see no obvious functionality on top of the GNU column program.

It is integrated with various Git commands, and its formatting is tailored to handle Git-specific outputs. Unlike the GNU column command, git column can be configured through Git's configuration system (.gitconfig).
It has options, like --nl "padding space on right border" that I do not see with GNU column.

Answer 2

Look into the man page of git-config, either git config --help or man git-config should give you man page. This option says to look into column.ui description, which I show here for you:

column.ui
   Specify whether supported commands should output in columns. 
   This variable consists of a list of tokens separated by spaces or commas:

   These options control when the feature should be enabled (defaults to never):

   always
       always show in columns

   never
       never show in columns

   auto
       show in columns if the output is to the terminal

   These options control layout (defaults to column). Setting any of these implies always if none of always, never, or auto are specified.

   column
       fill columns before rows

   row
       fill rows before columns

   plain
       show in one column

   Finally, these options can be combined with a layout option (defaults to nodense):

   dense
       make unequal size columns to utilize more space

   nodense
       make equal size columns