ScriptOptions
This explains the font-patcher command line options for version v3.0.2-168 (4.7.2).
Nerd Fonts Patcher v3.0.2-168 (4.7.2) (ff 20230101)
usage: font-patcher [-h] [-v] [-s] [--variable-width-glyphs] [--debug [{0,1,2,3}]] [-q] [--careful]
[-ext EXTENSION] [-out OUTPUTDIR] [--makegroups [{-1,0,1,2,3,4,5,6}]] [-c]
[--codicons] [--fontawesome] [--fontawesomeext] [--fontlogos] [--material]
[--octicons] [--powersymbols] [--pomicons] [--powerline] [--powerlineextra]
[--weather] [--boxdrawing] [--configfile CONFIGFILE] [--custom CUSTOM] [--dry]
[--glyphdir GLYPHDIR] [--has-no-italic] [-l] [--metrics {HHEA,TYPO,WIN}]
[--name FORCE_NAME] [--postprocess POSTPROCESS] [--removeligs]
[--xavgcharwidth [XAVGWIDTH]] [--progressbars | --no-progressbars]
font
Only the long form is listed here. Expand option to get full explanation.
font The path to the font to patch (e.g., Inconsolata.otf)
The to-be-patched font file, relative and absolute path is allowed. All font formats that fontforge
can open are allowed, but usually .ttf or .otf are best. Also .ttc is possible, but the size
savings that would be possible are not utilized.
--help show this help message and exit
The message is obviously not good and long enough, or you would not be looking here. Hope
you find something useful.
--version show program's version number and exit
The detailed version is anyhow printed on every start of the font-patcher with Release and script versions,
so this is most useful for scripts that want to check the version rather than humans.
--mono Whether to generate the glyphs as single-width (Nerd Font Mono)
Create a truly monospaced font (Nerd Font Mono
That means that the added icons are also one (1) 'cell' wide which some people find too small.
On the other hand these fonts work with all terminals because there are no problematic glyph sizes, all fits into the cells.
Without any option a
Nerd Font is created: Here the symbols are typically a bit wider than one cell (1.5 widths) to make
them more readable. The 'advance width' is still one cell, so the next glyph will be printed on top of the
right half of the symbol - you need to add a blank after any icon. A lot of executables and terminals can work with this.
See also
variable-width-glyphs
--variable-width-glyphs Do not adjust advance width (no "overhang") (Nerd Font Propo)
Create a proportional font (Nerd Font Propo
That means that the added icons are wider than one (1) 'cell' and really occupy that space -
their advance width is the same as the visual width. No need to add any blanks but still bigger
icons than a Nerd Font Mono font. This is most useful for GUI contexts instead terminal contexts.
Without any option a
Nerd Font is created: Here the symbols are typically a bit wider than one cell (1.5 widths) to make
them more readable. The 'advance width' is still one cell, so the next glyph will be printed on top of the
right half of the symbol - you need to add a blank after any icon. A lot of executables and terminals can work with this.
See also
mono
--debug [N] Verbose mode
The patcher can output diagnostics and details of what is does and sometimes what it guesses.
This can help in problematic cases or when you want to create an Issue report.
Possible values are
- 0 = no messages (default)
- 1 = just to a logfile
- 2 = just to the console (this is also used if you just give
--debugwithout number) - 3 = log both to console and logfile
The 'to file' option is useful when you patch more than one font and want to have the diagnostics in one place afterwards. The file will be
font-patcher-log.txt and be placed
where the script itself is. The lines in that file get the source font file name (which the
output to the console does not have).
--quiet Do not generate verbose output
Some standard output is suppressed. Usually best when you also redirect stderr to discard it (... 2>/dev/null).
--careful Do not overwrite existing glyphs if detected
If a codepoint is already in use in the unpatched font it will not be replaced if you give this option.
Useful if you find that glyphs you like have been replaced after patching. On the other hand the icons
that we would have put there are then of course missing.
--extension EXTENSION Change font file type to create (e.g., ttf, otf)
Specify the format of the generated patched font. Usually you should keep the original font's format.
--outputdir OUTPUTDIR The directory to output the patched font file to
Normally the patched font ends up in the current working directory, but you can specify a different
relative or absolute path here. Make sure you can write to that directory.
--makegroups [N] Use alternative method to name patched fonts
Sometimes the name of the patched font is rather long. With this option you can select a strategy to
shorten it. See the following table which component gets shorted:
Original font name: Hugo Sans Mono ExtraCondensed Light Italic
NF Family aggessive
-1 no renaming at all (keep old names and versions etc) --- --- ---
0 turned off, use old naming scheme [-] [-] [-]
1 HugoSansMono Nerd Font ExtraCondensed Light Italic [ ] [ ] [ ]
2 HugoSansMono Nerd Font ExtCn Light Italic [ ] [X] [ ]
3 HugoSansMono Nerd Font XCn Lt It [ ] [X] [X]
4 HugoSansMono NF ExtraCondensed Light Italic [X] [ ] [ ]
5 HugoSansMono NF ExtCn Light Italic [X] [X] [ ]
6 HugoSansMono NF XCn Lt It [X] [X] [X]
--complete Add all available Glyphs
Patch in all sets...
--codicons Add Codicons Glyphs
Patch in this set: https://github.com/microsoft/vscode-codicons
See Glyph Sets and Code Points Overview for details.
--fontawesome Add Font Awesome Glyphs
Patch in this set: http://fontawesome.io
See Glyph Sets and Code Points Overview for details.
--fontawesomeext Add Font Awesome Extension Glyphs
Patch in this set: https://andrelzgava.github.io/font-awesome-extension
See Glyph Sets and Code Points Overview for details.
--fontlogos Add Font Logos Glyphs
Patch in this set: https://github.com/Lukas-W/font-logos
See Glyph Sets and Code Points Overview for details.
--material Add Material Design Icons
Patch in this set: https://github.com/templarian/MaterialDesign
See Glyph Sets and Code Points Overview for details.
--octicons Add Octicons Glyphs
Patch in this set: https://octicons.github.com
See Glyph Sets and Code Points Overview for details.
--powersymbols Add IEC Power Symbols
Patch in this set: https://unicodepowersymbol.com
See Glyph Sets and Code Points Overview for details.
--pomicons Add Pomicon Glyphs
Patch in this set: https://github.com/gabrielelana/pomicons
See Glyph Sets and Code Points Overview for details.
--powerline Add Powerline Glyphs
See Glyph Sets and Code Points Overview for details.
--powerlineextra Add Powerline Extra Glyphs
Patch in this set: https://github.com/ryanoasis/powerline-extra-symbols
See Glyph Sets and Code Points Overview for details.
--weather Add Weather Icons
Patch in this set: https://github.com/erikflowers/weather-icons
See Glyph Sets and Code Points Overview for details.
--boxdrawing Force patching in (over existing) box drawing glyphs
The box drawing glyphs (2500 - 259f are not patched in if the original font already has all
of these. If only a subset exists the exiting glyphs are replaced by the Nerd Fonts Box set
to get the same style for all Box glyphs.
In some cases (e.g. when the determined cell size differs from the originally intended one) it can be better to do patch the Nerd Fonts Box set in, even if a complete set is already existing.
--configfile FILE Specify a file path for JSON configuration file (see sample: src/config.sample.json)
The patching process can be influenced by a configuration file. At the moment that is only used for --removeligs.
--custom CUSTOM Specify a custom symbol font, all glyphs will be copied; absolute path suggested
If you have a font with some few glyphs that you want to patch in, this is the option for that.
Usually the custom symbol font needs to be specifically crafted for your purpose.
The scaling and other details can not be influenced.
--dry Do neither patch nor store the font, to check naming
This generated most of the warning messages a real run would without producing any file.
--glyphdir GLYPHDIR Path to glyphs to be used for patching
The icon set font files are expected to be in some specific directory relative to the script file.
When the files reside somewhere else you can specify the path to them here. This is very seldom useful.
--has-no-italic Font family does not have Italic (but Oblique), to help create correct RIBBI set
The font-patcher tries to generate RIBBI sets of fonts. RIBBI means 'Regular Italic Bold Bold-Italic'. A lot
applications use/expect fonts to be such a set-of-four. But some fonts have (only) Oblique instead of Italic -
in that case you want a 'Regular Oblique Bold Bold-Oblique' set and need to specify this option.
--adjust-line-height Whether to adjust line heights (attempt to center powerline separators more evenly)
If the determined cell height is odd in design units it will be coerced to a even number by adding 1. Well, one design
unit is usually 1/500th to 1/2000th of the full height, so you will hardly ever see any difference.
Probably this option in completely useless and is only kept for historic reasons.
--metrics METRIC Select vertical metrics source (for problematic cases)
The baseline to baseline distance of a font can be specified in three different ways. Sometimes a source font
contradicts itself because the three metrics do not agree. The script tries then to come up with a reasonable
estimate. If that is wrong you can force another metric to be used. Use --debug to see the three values.
--name MODE-OR-NAME Specify naming source ('full', 'postscript', 'filename', or concrete free name-string)
The font-patcher has to find out the name and the weight and style of the font. That can be challenging and the
script tries to guess which is best.
If the naming of the patched font is unsatisfactory you can specify the naming source here (the FullName, the PostscriptName, or try parsinging the filename).
If all fails you can specify a free string here that is used as naming source and parsed.
--postprocess SCRIPT Specify a Script for Post Processing
Sometimes you want to call some helper after patching. The helper is called in a subshell with the
generated patched font file's name as argument. That had been used in the past to automatically
hint the patched font, but that should not be necessary anymore.
--removeligs Removes ligatures specificed in JSON configuration file (needs --configfile)
This does not automatically remove all ligatures! Instead it removes some tables from the font, which need to
be specified in a config file. Removing tables can break the font in various ways, be careful.
This is used for prepatched fonts that are problematic because codepoints we want to patch are used in some ligatures.
--xavgcharwidth [N] Adjust xAvgCharWidth (optional: concrete value)
In some very rare cases the xAvgCharWidth is important to keep. Patching in wider icons changes this value.
- If just the option is specified (without numbger) the
xAvgCharWidthis copied over from the source - If a number is added that number is used as
xAvgCharWidth - If the number added is zero we will calculate the old style
xAvgCharWidth, which ignores our added icons