Does `~/.gitconfig` syntax require spaces, tabs, or either for indenting?

Question

I was editing my ~/.gitconfig and noticed there was mixed tabs/spaces. Usually mixing tabs/spaces is bad but when I tried to look up the documentation for what is allowed syntax requirement I couldn't find an answer.

Does ~/.gitconfig syntax require spaces, tabs, or either for indenting?

Where is this explained in the git-config documentation?

Answer 1

Does ~/.gitconfig syntax require spaces, tabs, or either for indenting?
Where is this explained in the git-config documentation?

Git 2.45 (Q2 2024) clarifies the documentation.

This clarification comes from a bug: "git config"^(man) corrupted literal HT (Horizontal Tabulation) characters written in the configuration file as part of a value, which has been corrected with Git 2.45 (Q2 2024), batch 13.

See commit e6895c3, commit d71bc1b, commit f0b8944, commit 0d49b1e (21 Mar 2024) by Dragan Simic (dragan-simic).
^{(Merged by Junio C Hamano -- gitster -- in commit 521df68, 01 Apr 2024)}

config.txt: describe handling of whitespace further

^{Helped-by: Junio C Hamano
Helped-by: Eric Sunshine
Signed-off-by: Dragan Simic}

Make it more clear what the whitespace characters are in the context of git configuration files, and significantly improve the description of the leading and trailing whitespace handling, especially how it works out together with the presence of inline comments.

config now includes in its man page:

The syntax is fairly flexible and permissive.
Whitespace characters, which in this context are the space character (SP) and the horizontal tabulation (HT), are mostly ignored.
The '#' and ';' characters begin comments to the end of line. Blank lines are ignored.

config now includes in its man page:

Whitespace characters surrounding name, = and value are discarded.
Internal whitespace characters within 'value' are retained verbatim.
Comments starting with either # or ; and extending to the end of line are discarded.
A line that defines a value can be continued to the next line by ending it with a backslash (\);
the backslash and the end-of-line characters are discarded.

config now includes in its man page:

If value needs to contain leading or trailing whitespace characters, it must be enclosed in double quotation marks (").
Inside double quotation marks, double quote (") and backslash (\) characters must be escaped: use \" for " and \\ for \.

---

The bug is illustrated in:

config: really keep value-internal whitespace verbatim

^{Signed-off-by: Dragan Simic}

Fix a bug in function parse_value() that prevented whitespace characters (i.e. spaces and horizontal tabs) found inside configuration option values from being parsed and returned in their original form.
The bug caused any number of consecutive whitespace characters to be wrongly "squashed" into the same number of space characters.

This bug was introduced back in July 2009, in commit ebdaae3 (config: Keep inner whitespace verbatim, 2009-07-30, Git v1.6.5-rc0 -- merge).

Further investigation showed that setting a configuration value, by invoking git-config(1), converts value-internal horizontal tabs into "\t" escape sequences, which the buggy value-parsing logic in function parse_value() didn't "squash" into spaces.
That's why the test included in the ebdaae3 commit passed, which presumably made the bug remain undetected for this long.
On the other hand, value-internal literal horizontal tab characters, found in a configuration file edited by hand, do get "squashed" by the value-parsing logic, so the right choice was to fix this bug by making the value-internal whitespace characters preserved verbatim.

Answer 2

No, .gitconfig does not require spaces and/or tabs for indenting.

Whitespace at the start of each line is ignored, which means you're free to indent or not indent, spaces or tabs, it doesn't matter.

Only whitespace inside values is retained verbatim, other whitespace is ignored.

So feel free to use spaces and/or tabs as you see fit, or just remove indentation altogether.

Note that the gitconfig syntax allows you to continue lines onto the next line, whitespace inside such lines will be kept, but here:

 name = value
^    ^ ^     ^

all of that whitespace is effectively ignored, whereas here:

name = value1 value2
             ^

this is kept.

---

To answer your question, not all of this is fully documented so some of this behavior is by observation, but most of it is, on the git-config documentation page:

The syntax is fairly flexible and permissive; whitespaces are mostly ignored. The # and ; characters begin comments to the end of line, blank lines are ignored.

and

Leading whitespaces after name =, the remainder of the line after the first comment character # or ;, and trailing whitespaces of the line are discarded unless they are enclosed in double quotes. Internal whitespaces within the value are retained verbatim.