Fontist

After installation, please fetch formulas via the fontist command:

Depends on ffi-libarchive-binary which has the following requirements:

• zlib

• Expat

• OpenSSL (for Linux only)

These dependencies are generally present on all systems.

These commands makes possible to operate with fonts via command line.

The CLI properly supports exit status, so in a case of error it returns a status code higher or equal than 1.

Searches are case-insensitive for ease of use.

All commands support the following global options:

--preferred-family

Search using the “preferred family” name of a font. (instead of the “default family” name, the default prior to Fontist v1.10.)

-q, --quiet

Print as little information as possible, mostly critical errors.

-v, --verbose

Set the log level to debug. It prints formulas excluded during installation and information for developers of fontist.

-c, --no-cache

Prefer direct download even when a file is already cached in a system.

Fontist checks whether this font is already installed, and if not, then installs the font and returns its installed paths.

The font name is the only argument to be supplied.

By default, all matching styles (according to the font’s “default family” name) are installed.

To install all fonts specified in a Fontist formula, use the -F, --formula option.

Here, courier_prime is the filename of the formula located at the public Fontist Formula repository (courier_prime.yml).

You can also specify the human-readable name of the formula. This name is derived from the filename, with underscores replaced by spaces. It’s not case-sensitive, meaning you can use capital letters if you prefer.

Installation by the formula name supports suggestions in CLI when input is partial:

If there are several formulas with a requested font, then fontist searches for the newest version of the font among formulas with size below a limit (300 MB). This behavior can be changed with options.

Supported options:

-f, [--force]

Install even if already installed in system

-F, [--formula]

Install whole formula instead of a font

-a, [--accept-all-licenses]

Accept all license agreements

-h, [--hide-licenses]

Hide license texts

-p, [--no-progress]

Hide download progress

-V, [--version=VERSION]

Install particular version of a font

-s, [--smallest]

Install the smallest font by file size if several

-n, [--newest]

Install the newest version of a font if several

-S, [--size-limit=N]

Specify upper limit for file size of a formula to be installed (default is 300 MB)

-u, [--update-fontconfig]

Update Fontconfig

Uninstalls any font supported by Fontist.

Returns paths of an uninstalled font, or prints an error telling that the font isn’t installed or could not be found in Fontist formulas. Aliased as remove.

Prints installed font paths with a corresponding formula.

Lists installation status of fonts supported by Fontist.

Returns locations of fonts specified in a YAML file as an input.

MANIFEST_FILE is the location of a manifest file that contains specification of one or multiple font and font styles.

A manifest file manifest.yml could look like:

The following command will return the following YAML output:

If one or more of requested fonts are missing, the "3" error code would be returned, and a message printed:

Install fonts from a YAML Fontist manifest:

Where manifest.yaml is:

Fontist supports system-wide settings for the following parameters:

fonts_path

Sets path where to install fonts (default: ~/.fontist/fonts)

open_timeout

Sets timeout for opening a connection during download (default: 10)

read_timeout

Sets timeout for reading the opened connection during download (default: 10)

Show current attributes in the config:

Assign a value to an attribute:

Restore a default value of an attribute:

Fontconfig is a software designed to provide fonts to other programs. It is typically used on Linux, but also available on macOS and Windows. Fontconfig is used by LibreOffice, GIMP, and many other programs.

It order to find fontist fonts, Fontconfig should be updated to include fontist paths. It can be done with the --update-fontconfig option of the install command, or by calling a special one:

It would create a config in ~/.config/fontconfig/conf.d/10-fontist.conf.

To remove it, please use:

The command above will clear fontist’s download cache

List of all commands could be seen by:

By default Fontist uses the ~/.fontist directory to store fonts and its files. It could be changed with the FONTIST_PATH environment variable.

The Fontist::Font is your go-to place to deal with any font using Fontist.

This interface allows you to find a font or install a font.

The fontist gem internally usages the Fontist::Formula interface to find a registered formula or fonts supported by any formula. Unless, you need to do anything with that you shouldn’t need to work with this interface directly. But if you do then these are the public interface it offers.

Fontist supports work with Fontconfig via the Ruby interface:

Newer versions of macOS provide on-demand installations of a wide range of licensed fonts. These macOS-specific add-on fonts can be installed via Fontist.

A typical use for installing macOS add-on fonts is to allow CI jobs on macOS environments to use these specially-licensed fonts not available on other platforms.

This blog post describes how this works:

• Fontist blog: Installing macOS-specific add-on fonts

For example, the "Canela" font is a commercial font that comes free with macOS.

Run this command to install Canela on macOS.

The full list of available fonts on various macOS versions can be found on the Apple Support site:

• Fonts in macOS 13 Ventura

• Fonts in macOS 12 Monteray

• Fonts in macOS 11 Big Sur

• NISC18030.ttf (GB18030 Bitmap) - macOS, more info in the NISC18030 issue

The full list of known problematic fonts:

• List of fonts excluded from usage

Fontist uses Git internally for fetching formulas and fonts.

In order to use Git functionality behind a proxy, you need to update your own Git config via the git config command or the ~/.gitconfig preference file.

There are many ways to configure your local Git install to use proxies.

The simplest, global way of setting a proxy for Git is the following.

• For HTTP

  git config --global http.proxy http://{user}:{pass}@{proxyhost}:{port}

• For HTTPS, you may need to handle SSL/TLS verification errors after setting the proxy since the encryption end is located at your HTTPS proxy endpoint:

  git config --global http.proxy https://{user}:{pass}@{proxyhost}:{port}
  git config --global https.proxy https://{user}:{pass}@{proxyhost}:{port}

• For SOCKS, you will need to decide on the SOCKS protocol

  git config --global http.proxy '{protocol}://{user}:{pass}@{proxyhost}:{port}'
  git config --global https.proxy '{protocol}://{user}:{pass}@{proxyhost}:{port}'

  For example,

  git config --global http.proxy 'socks5h://user:pass@socks-proxy.example.org'
  git config --global https.proxy 'socks5h://user:pass@socks-proxy.example.org'

The list of supported SOCKS protocols for the {protocol} field:

• socks://: for SOCKS below v5

• socks5://: for SOCKS v5

• socks5h://: for SOCKS below v5 + host resolution via SOCKS

You could actually set different proxy behavior for individual Git repositories — please see this great guide on how to use Git proxies (thanks to the GitHub user evantoli).

A Fontist repository is a Git repo which contains YAML Formula files. Fontist Formulas can be created manually within a Fontist repository (see examples), or auto-generated from a font archive.

A Fontist repository can be accessed either through HTTPS or SSH. In case of SSH, a corresponding SSH key should be setup with ssh-agent in order to access this custom repository.

The fontist repo setup command fetches a custom repository’s formulas, and stores the repository’s name and URL for later use.

The fontist repo setup command uses the following syntax.

Internally, all custom Fontist repository information is stored at ~/.fontist/formulas/Formulas/private.

For example, given a Fontist repository called "acme" accessible via a URL or an SSH address:

Once the custom Fontist repository is setup, one can install fonts from the repo through its formulas:

If the custom Fontist formula repository is updated, the repo update command is used to pull the newest changes:

For example, given a Fontist repository called "acme", the following command is used.

If there is a need to remove a registered Fontist repository, the repo can be removed with:

Custom Fontist formulas and Fontist repositories can be made private to require authentication.

For HTTPS and SSH Git Fontist repositories

Authorization of private archives in private formulas can be implemented with headers.

Here is an example which works with Github releases:

If the Fontist formula repository is a GitHub repo, a token can be obtained on the GitHub Settings > Tokens page. This token should have at least the repo scope for access to these assets.

To add a new attribute, change how formula is treated or completely replace the structure, there are 2 ways to change a formula format:

1. Use the min_fontist attribute in a formula. It sets a requirement for fontist to install the formula only if its version is equal or more than a specified version.

2. Use a new branch in the formulas repo, e.g. "v2", "v3", "v4", etc. After creating a new branch, it should be defined in Fontist.formulas_version

Google Fonts provides probably the largest collection of widely-used, freely and openly licensed fonts.

Fontist’s formula library includes support for all openly-licensed fonts provided through Google Fonts, and maintains Fontist formulas for all such fonts.

A GHA workflow checks for updated fonts on Google Fonts daily. In case an update is found, it’s added to the repo by the workflow.

SIL International is an internationally recognized faith-based nonprofit organization that serves language communities worldwide.

SIL provides a number of unique fonts that support smaller language communities that with Unicode code often not (yet) supported by mainstream fonts.

Fontist aims to support all SIL fonts and provides their formulas in the default Fontist formula repository.

They can be updated with:

macOS provides fonts which can be manually downloaded with Font Book.app.

To update macOS formulas:

Clone the repository.

Setup your environment.

Run the test suite

All official Fontist formulas are kept in the formulas repository.

If you’d like to add a new formula repository or change settings for an existing one, please refer to its documentation.

Releasing is done automatically with GitHub Actions. Just bump and tag with gem-release.

For a patch release (0.0.x) use:

For a minor release (0.x.0) use: