Tools frequently need to change their behavior based on values stored in
Git’s configuration files. These files may have complicated conditions
for including extra files, so it is difficult to produce an independent
parser. To avoid executing multiple processes to discover or modify
multiple configuration values, the git config-batch command allows a
single process to handle multiple requests using a machine-parseable
interface across stdin and stdout.
-z-
If specified, then use the NUL-terminated input and output format instead of the space and newline format. This format is useful when the strings involved may include spaces or newlines. See PROTOCOL for more details.
By default, the protocol uses line feeds (LF) to signal the end of a
command over stdin or a response over stdout.
The protocol will be extended in the future, and consumers should be
resilient to older Git versions not understanding the latest command
set. Thus, if the Git version includes the git config-batch builtin
but doesn’t understand an input command, it will return a single line
response:
unknown_command LF
These are the commands that are currently understood:
helpversion 1-
The
helpcommand lists the currently-available commands in this version of Git. The output is multi-line, but the first line provides the count of possible commands viahelp 1 count <N>. The next<N>lines are of the formhelp 1 <command> <version>to state that this Git version supports that<command>at version<version>. Note that the same command may have multiple available versions.Here is the current output of the help text at the latest version:
help 1 count 2 help 1 help 1 help 1 get 1
getversion 1-
The
getcommand searches the config key-value pairs within a given<scope>for values that match the fixed<key>and filters the resulting value based on an optional<value-filter>. This can either be a regex or a fixed value. The command format is one of the following formats:get 1 <scope> <key> get 1 <scope> <key> arg:regex <value-pattern> get 1 <scope> <key> arg:fixed-value <value>
The
<scope>value can be one ofinherited,system,global,local,worktree,submodule, orcommand. Ifinherited, then all config key-value pairs will be considered regardless of scope. Otherwise, only the given scope will be considered.If no optional arguments are given, then the value will not be filtered by any pattern matching. If
arg:regexis specified, then the rest of the line is considered a single string,<value-pattern>, and is interpreted as a regular expression for matching against stored values, similar to specifying a value toget config --get <key> "<value-pattern>". Ifarg:fixed-valueis specified, then the rest of the line is considered a single string,<value>, and is checked for an exact match against the key-value pairs, simmilar togit config --get <key> --fixed-value "<value>".At mmost one key-value pair is returned, that being the last key-value pair in the standard config order by scope and sequence within each scope.
If a key-value pair is found, then the following output is given:
get 1 found <key> <scope> <value>
If no matching key-value pair is found, then the following output is given:
get 1 missing <key> [<value-pattern>|<value>]
where
<value-pattern>or<value>is only supplied if provided in the command.
When -z is given, the protocol changes in some structural ways.
First, each command is terminated with two NUL bytes, providing a clear boundary between commands regardless of future possibilities of new command formats.
Second, any time that a space would be used to partition tokens in a
command, a NUL byte is used instead. Further, each token is prefixed
with <N>: where <N> is a decimal representation of the length of
the string between the : and the next NUL byte. Any disagreement in
these lengths is treated as a parsing error. This use of a length does
imply that "0:" is the representation of an empty string, if relevant.
The decimal representation must have at most five numerals, thus the maximum length of a string token can have 99999 characters.
For example, the get command, version 1, could have any of the
following forms:
3:get NUL 1:1 NUL 5:local NUL 14:key.with space NUL NUL 3:get NUL 1:1 NUL 9:inherit NUL 8:test.key NUL 9:arg:regex NUL 6:.*\ .* NUL NUL 3:get NUL 1:1 NUL 6:global NUL 8:test.key NUL 15:arg:fixed-value NUL 3:a b NUL NUL
The output is modified similarly, such as the following output examples,
as if the input has a parse error, a valid help command, a get
command that had a match, and a get command that did not match.
15:unknown_command NUL NUL 4:help NUL 1:1 NUL 5:count NUL 1:2 NUL NUL 4:help NUL 1:1 NUL 4:help NUL 1:1 NUL NUL 4:help NUL 1:1 NUL 3:get NUL 1:1 NUL NUL 3:get NUL 1:1 NUL 5:found NUL 8:test.key NUL 5:value NUL NUL 3:get NUL 1:1 NUL 7:missing NUL 8:test.key NUL NUL