bat: the one-line override that teaches bat your file extensions

After installing bat, you opened a .conf file in a project. The output is plain text. You opened a .applog file your team emits from a custom service. Plain text again.

The Modern CLI Stack PDF shows how to install bat, and then points at --list-languages for getting the list of language entries. But it does not cover --map-syntax.

Let's discuss three examples of using that override feature, with the --list-languages lookup the override depends on.

The <glob> is a gitignore-style pattern (*.conf, *.applog, *.audit). The <name> value is the case-sensitive language identifier from bat --list-languages. Get the name wrong and bat prints the file as plain text.

The override can be done in two places. As a CLI flag, it applies to one invocation. In bat's config file at ~/.config/bat/config (a flat CLI-flag file, one option per line), it persists across every bat run in that account:

The catalog ships with nginx (lowercase), and its built-in globs only match /etc/nginx/**/*.conf and nginx.conf. A project-local nginx/site.conf or a custom service config with the .conf extension would be handled as plain text. So you need the override:

After the override, bat on proxy.conf highlights server, listen, location, and proxy_pass as nginx keywords.

A team that emits logs with a domain-specific extension (*.applog, *.audit, *.tracelog) gets plain text in bat. The catalog has log (lowercase, exact name from --list-languages), so use the override:

After the override, the timestamp + level pattern at the start of each line highlights with the Log File grammar.

Some teams emit a separate audit trail (*.audit, *.auditlog) distinct from the operational log. The catalog has log, same as the previous *.applog recipe, and the same binding fires for the audit shape using the override:

After the override, the key=value and timestamp patterns in each audit line highlight with the Log File grammar.

Every <name> in the recipes above came from this command:

The list is the source to use to find the value of <name>. The override is the line that points at it.

Note that if a future bat version renames an entry (uncommon but possible), the recipe will silently break. Run bat --list-languages | grep <name> after any bat upgrade to confirm the name is still there.

Pick a file in your file system whose extension bat does not recognize. Run bat <file> and note the plain-text output. Run bat --list-languages | grep -i '<extension-keyword>' and copy the matching <name> value. Add --map-syntax "<extension>:<name>" to your bat config file ~/.config/bat/config (create the file if it does not exist yet — bat does not create it for you). Run bat <file> again and watch the highlighting succeed. If nothing changes, your <name> is not in the catalog — re-run the grep and pick a different one.

bat --no-config is the diagnostic trick when a binding looks wrong: it tells you whether the bug is in your override or in bat's upstream catalog. If bat --no-config <file> highlights and bat <file> does not, the binding is the problem; if neither highlights, the upstream catalog does not have a matching entry and the override's <name> is the wrong target.