Why Context Beats Blind Spellcheck: Git, Filesystems, and Running Systems
The most revealing The Fuck rules are not the ones that correct a single misspelled word. They are the rules that interpret the vocabulary of the program that failed or inspect the machine around it. This chapter follows that difference through a Git case, then compares it with directory, npm, and occupied-port repairs. The goal is to classify each suggestion by its evidence and assumptions, so readers can tell when The Fuck is following a diagnostic, when it is consulting current local state, and when specificity creates a new maintenance or safety dependency.
Case one: Git lets the failed tool explain itself
Consider a command such as git brnch. A generic spellchecker can notice that brnch is close to branch, but that resemblance is not enough to establish that Git is the program being called, that the token is the subcommand, or that the replacement belongs in that position. The Git-specific rule starts with those conditions. It checks that the command is in Git's scope and that the output contains Git's characteristic message for an unknown command together with a suggestion section.
The rule then extracts the broken Git word from the diagnostic and reads the commands Git suggested. The replacement helper preserves the surrounding script while substituting the matched word. The important evidence is not only the distance between brnch and branch; it is that Git itself identified the token as an invalid subcommand and named a plausible alternative. The rule is still a proposal—Git's suggestion may not match the user's intention—but its reasoning is narrower and more inspectable than a general rewrite over every word in the command.
The generic missing-command rule shows the other side of the same boundary. It looks for an executable that cannot be found, checks the program's “not found” style output, and compares the missing name with executables and aliases available on the machine. A close match from that inventory can be more useful than a static dictionary because it reflects what the user's shell can actually invoke. It can also produce different candidates on different machines. The available command vocabulary is evidence of possibility, not evidence of intent.
The Git upstream case goes further. A user can run git push successfully as a syntactically valid command and still receive a failure saying that the current branch has no upstream branch. The relevant rule does not search for a typo. It recognizes a push command and looks for Git's upstream setup instruction in the output. It extracts the suggested remote and branch arguments, removes options that would otherwise be duplicated, and reconstructs a new push command around Git's advice. The correction is a translation from a diagnostic into an action, not a lexical substitution.
That distinction changes how the candidate should be reviewed. With a typo, the reader can ask whether the replacement word is the intended subcommand. With the upstream case, the reader must also ask whether the named remote, branch, and publishing action are appropriate.