Google Fonts

google/fonts repository explained

🦉 google/fonts is the GitHub repository that is used as a staging area to upload font families to Google Fonts.

Once your project is ready, and you are sure it meets all the font and production requirements; as well as you have located your files in a GitHub repository that follows the required structure, then the definitive step to contributing your font to Google Fonts is to submit it as a Pull Request to google/fonts repository.

This section will help users understand which are the directories, files, and python modules included in the Google/Fonts repository and how they are related.

Background reading:
must→ Upstream repository structure

Table of contents

• google/fonts repository explained
  • Repository structure
  • Family directories
  • Designers catalog
  • Axis registry
  • Lang directory
  • Push lists

google/fonts repository explained

Repository structure

.
├── AUTHORS
├── CODE_OF_CONDUCT.md
├── CONTRIBUTING.md
├── CONTRIBUTORS
├── README.md
├── TRIVIA.md
├── apache
├── axisregistry
├── catalog
├── knowledge
├── lang
├── ofl
├── ufl
├── to_production.txt
└── to_sandbox.txt

Family directories

The ofl, ufl and apache directories contain font families. There is a directory per family published by GF and each directory has the following structure:

.
├── article/ARTICLE.en_us.html
├── METADATA.pb
├── License (OFL.txt, UFL.txt, License.txt)
├── FontFamily-Regular.ttf
└── upstream.yaml

Each file has the following purpose:

• ARTICLE.en_us.html: describes the font family
• METADATA.pb: contains metadata related to the family
• License: License for the font family. Valid choices are OFL.txt, UFL.txt, License.txt. If you’re unsure what license to use, we recommend OFL.txt
• .ttf: Family font files.
• upstream.yaml: file linking the font files with the upstream. It is used by the Packager (our onbaording tool) to facilitate the font upgrading process.

If the family is a variable font family, another directory called static can be included to contain the static (non-variable) fonts for the family:

.
├── DESCRIPTION.en_us.html
├── METADATA.pb
├── License (OFL.txt, UFL.txt, License.txt)
├── FontFamily[axis].ttf
├── static
│   ├── FontFamily-Regular.ttf
│       └── FontFamily-Bold.ttf
└── upstream.yaml

This static directory is mandatory if the static fonts are manually hinted; otherwise, it should not be added at all.

Designers catalog

.
├── info.pb
├── bio.html
└── image.png

Each credited entity on Google Fonts should have a registered profile in google/fonts/catalog/designers. This profile appears in the about section of the specimen page.

You can request the addition or modification of your name, bio, and image using this form.

Find more information about the requirements for these files in the designer profile chapter.

Axis registry

.
├── axisregistry

Google Fonts supports all the Microsoft registered axes for variable fonts, but it has its own Axis Registry, which defines the names, ranges, and defaults of additional axes supported by the API. This registry is used to generate the static instances of each variable family (which you can find in the downloadable zip file); the API will generate only those locations registered in the registry.

This directory is a git subtree that is automatically updated with changes in the googlefonts/axisregistry repository. The contents of this directory should not be changed in commits that are pushed to the google/fonts repository. Rather, make edits in a pull request on the googlefonts/axisregistry repository. google/fonts repository maintainers can then pull the git subtree changes in to the axisregistry directory by executing the following command from the root of google/fonts:

git subtree pull --prefix=axisregistry https://github.com/googlefonts/axisregistry.git main

Once the main branch from the submodule is pulled, you will need to push in a new branch upstream.

Important: When merging a pull request in the google/fonts repo which contains a subtree pull, merge it using the “Create a merge commit” button and not the “Squash and merge” button. If we squash and merge, the subtree’s history is squashed into a single commit which will cause merge conflicts for the next person who has to do a subtree pull.

Lang directory

.
├── lang

This Python module provides the API with data about languages/regions/scripts for use in the language-support categorization of the font families in the Google Fonts collection.

This directory is a git subtree that is automatically updated with changes in the googlefonts/lang repository. The contents of this directory should not be changed in commits that are pushed to the google/fonts repository. Rather, make edits in a pull request on the googlefonts/lang repository.

Once you have a set of changes that you want to be merged into google/fonts, the procedure is:

• Make a release of gflanguages by pushing an annotated tag in the googlefonts/lang directory:

% cd gflanguages
% git tag -a v0.X.Y
(fill in the release notes in your editor)
% git push --tags

• Switch to the google/fonts repository, and create a new branch:

% cd ../fonts
% git checkout -b lang-v0.X.Y

• Pull the git subtree changes into the lang directory by executing the following command in the root of the google/fonts repository:

% git subtree pull --prefix=lang https://github.com/googlefonts/lang.git main

• Create a new google/fonts pull request for this branch.

• Label the pull request with | Lang so that the push-list script will know what kind of paths are expected in the push lists.

Important: When merging the pull request in the google/fonts repo which contains a subtree pull, merge it using the “Create a merge commit” button and not the “Squash and merge” button. If we squash and merge, the subtree’s history is squashed into a single commit which will cause merge conflicts for the next person who has to do a subtree pull.

Push lists

• to_sandbox.txt is a list of font directories or designer directories to be pushed to sandbox.
• to_production.txt is a list of fonts directories or designer directories to be pushed to production. Once the elements (fonts, bio, etc) have been checked and validated in sandbox, they can be sent to the API so users can have access to them. We can only push to production something that was first pushed to sandbox.

Further reading:
team  Description file
team  Designer profile
team  METADATA file

This site is open source. Improve this page.