core.fsmonitor is a program exactly when git cannot read it as a boolean
A repository arrives as plain files, and it brings its own configuration with it. A few of those keys name programs git starts before you have typed anything more adventurous than git status. core.fsmonitor is the awkward one: the same key holds either a boolean that selects the monitor built into git, or the command git runs as a hook. Which one you are looking at is not a judgement call, it is a parse, and the only parser whose opinion counts is the one inside the binary that will later execute the value.
That is the rule I kept landing on while writing gitdisarm, which reads a repository's git configuration and prints every program that configuration would make git run, each with the override that takes it away. With core.fsmonitor the temptation is a heuristic: if the value looks like a path, or has a slash in it, or is not one of six known words, call it a command. A heuristic of that shape is wrong in both directions at once. It flags a TRUE that git reads as a plain boolean, and it waves through a value git refuses to read as a boolean and therefore hands to a shell. Both failures are quiet. Only one of them matters.
Two rows for one key, and the order between them#
The catalog in catalog/catalog.go is data: one row per key pattern, carrying the family the key belongs to and the override that disarms it. core.fsmonitor gets two rows. The first is conditional, matching only when the value is one git reads as a boolean, and it classifies the entry Inert. The second is unconditional, classifies the entry Executes, and carries the override -c core.fsmonitor=false. Classify walks the rows in order, and the first match wins.
The ordering is the design. The narrow conditional row is the exception, the broad unconditional row is the rule, and the fallthrough points towards reporting rather than away from it. A value the condition cannot vouch for does not land in some third bucket of things the tool is unsure about. It lands on the row that says git will run this.
func (r *Rule) matches(e gitconfig.Entry) bool {
if e.Section != r.section {
return false
}
if r.key != "" && e.Key != r.key {
return false
}
if r.sub == withSub && e.Subsection == "" {
return false
}
if r.sub == withoutSub && e.Subsection != "" {
return false
}
switch r.value {
case boolValue:
_, ok := parseBool(e.Value)
return ok
case bangValue:
return strings.HasPrefix(strings.TrimLeft(e.Value, " \t"), "!")
}
return true
}Look at what the boolValue case throws away. It discards the truth and keeps only ok. Whether the monitor ends up enabled or disabled is git's business and no concern of a tool that is not going to run anything. Whether the value was readable as a boolean at all is the only question the catalog has to answer. The same two-row shape serves pager.<name> and alias.<name>, where the condition is bangValue (an expansion beginning with !) instead.
The condition is git's grammar, including the parts nobody quotes#
parseBool mirrors git's reader rather than approximating it:
func parseBool(v string) (truth, ok bool) {
switch strings.ToLower(v) {
case "":
return false, true
case "true", "yes", "on":
return true, true
case "false", "no", "off":
return false, true
}
n, ok := parseInt(v)
return n != 0, ok
}Two things in those few lines are easy to get wrong. The empty value is a boolean, and it is false: a line reading core.fsmonitor = is not an empty command. And the words are matched whole, against the whole value lowercased, with no trimming at all. Git compares the words and scans the integers, and those are different operations with different tolerances. The scanner below accepts leading whitespace, the comparison above does not. A tool that helpfully trimmed before comparing would disagree with the thing that executes the value, which is the only disagreement that can hurt anyone.
The integer scanner is where the surprises live#
func parseInt(v string) (int64, bool) {
const max = 1<<31 - 1
s := strings.TrimLeft(v, " \t\n\v\f\r")
negative := false
if s != "" && (s[0] == '+' || s[0] == '-') {
negative = s[0] == '-'
s = s[1:]
}
base := 10
switch {
case strings.HasPrefix(s, "0x"), strings.HasPrefix(s, "0X"):
base, s = 16, s[2:]
case len(s) > 1 && s[0] == '0':
base = 8
}
n := digitRun(s, base)
if n == 0 {
return 0, false
}
val, err := strconv.ParseUint(s[:n], base, 64)
if err != nil {
return 0, false
}
factor := uint64(1)
switch unit := s[n:]; {
case unit == "":
case strings.EqualFold(unit, "k"):
factor = 1024
case strings.EqualFold(unit, "m"):
factor = 1024 * 1024
case strings.EqualFold(unit, "g"):
factor = 1024 * 1024 * 1024
default:
return 0, false
}
if val > max/factor {
return 0, false
}
val *= factor
if negative {
return -int64(val), true
}
return int64(val), true
}Four properties of that function decide what the report says. The prefix picks the base: 0x or 0X is hexadecimal, and a leading 0 followed by at least one more digit is octal. digitRun demands at least one digit valid in that base, so a value that is all prefix and no number gets refused. Exactly one k,m or g, in either case, multiplies by 1024, 1024 squared or 1024 cubed, and anything else left over after the digits refuses the whole value: a second unit, a stray letter, a space that survived quoting. Finally the result is bounded by 1<<31 - 1 after the factor is applied, tested as val > max/factor before the multiplication, so you cannot jump the bound by overflowing into it.
That last property has a consequence worth stating plainly: 1g is a boolean and 2g is not.
| value | git's reader | gitdisarm |
|---|---|---|
TRUE,On,no, empty |
boolean | inert, not printed |
0x10 |
hexadecimal 16, true | inert |
010 |
octal 8, true | inert |
08 |
base 8 stops after 0; 8 is trailing text |
reported as a program |
16k |
16384, true | inert |
1g |
1073741824, true | inert |
2g |
over the 1<<31 - 1 bound |
reported as a program |
-1 |
integer, non-zero, true | inert |
"true " quoted, trailing space |
neither a whole word nor an integer | reported as a program |
The quoted row is the one that earns the exactness. The configuration parser decides which bytes reach the value, and a quoted value keeps its spaces. A value of true is therefore reachable from a file, is not a boolean to git, and is text git would hand to a shell. 2g looks absurd in a report until you remember that the overflow bound is part of the grammar. A tool that treats that grammar as roughly numbers and some words will disagree with git exactly at the values an attacker gets to choose.
What the report can say because the condition is exact#
Two things hold at once here, and no heuristic delivers them together. A mixed-case TRUE, an Off, a 16k come back inert and never get printed, which is what keeps a report short enough that somebody reads it. And everything the grammar refuses is printed as a finding whose text says git cannot read the value as a boolean, carrying the value exactly as the file wrote it, with the override beside it.
f := catalog.Classify(entry)
if f.Class == catalog.Executes {
fmt.Printf("%s runs %q — disarm with: git %s …\n", catalog.Name(entry), entry.Value, f.Disarm)
}The override on that row is -c core.fsmonitor=false rather than an emptied value. Both disarm it, since the empty string is a boolean too, but false reads as a decision rather than as a deletion that stopped halfway.
None of this makes a short report a clean report, and the tool is written not to let anyone believe otherwise. NotCovered names what can still end in a program being run and what the catalog has no verdict for (hook.<name>.command,include.path,core.gitProxy,uploadpack.packObjectsHook, a template directory, the executables already sitting in .git/hooks), and it is printed at the end of every run. Exit status 0 is documented as no key this catalog covers names a program, which is a narrower claim than safe and is meant to be.
What I would do differently#
Mirroring another program's parser is a dated claim, and I treat it as one: the catalog carries its own version and the git version its rows were read from, so a stale mirror is at least legible as stale. What I would tighten is the direction of verification. internal/gitoracle/bool.go exists because the mirror is worth only as much as the comparison against the original, and I would rather have the boolean grammar checked against an installed git than against my reading of its source, every time, than treat that check as a nicety. The source moves, and a copy that nobody re-compares probably drifts into a heuristic wearing a parser's name.
The shape of this mistake is not specific to git. In payment integrations I have watched the same thing happen: a sender normalizes a value, trims it, re-cases it, pads a decimal, and the receiver parses the original grammar, and the bug lives in the gap between the two readings rather than in either one. Whenever one program decides whether a value is data and another decides whether to execute it, the second one owns the grammar. Copy it, bound and units and all, or do not claim to know.