font-v

About

font-v is an open source font version string library (libfv) and executable (font-v) for reading, reporting, modifying, and writing OpenType name table ID 5 records and head table fontRevision records in *.otf and *.ttf fonts.

font-v is built with Python and can be used on Linux, macOS, and Windows platforms with current versions of the Python 2 and Python 3 interpreters.

Contents

• Installation
• font-v Executable Usage
• libfv Library Usage
• libfv Library API Documentation
• Contributing to font-v
• License

Installation

The libfv library and the font-v executable are installed simultaneously with the following installation instructions.

Installation with the pip package manager is the recommended approach.

Install with pip

Install with pip using the following command:

$ pip install font-v

Upgrade with pip

Upgrade to a new version of font-v with the following command:

$ pip install --upgrade font-v

font-v Executable Usage

font-v is executed with a set of subcommands and options that define your command line request.

$ font-v [subcommand] (options) [font path 1] ([font path ...])

Available subcommands and options

Subcommands

report

Report OpenType name table ID 5 and head table fontRevision records

Option:

• --dev - include all name table ID 5 x platformID records in report

write

Write version number to head table fontRevision records and version string to name table ID 5 records.

Options:

The following option is used with write to modify the version number in both the head fontRevision record and the name ID 5 record(s):

• --ver=[version #] - modify current version number with a new version number using 1.000, 1_000 or 1-000 syntax on the command line (the latter two formats are provided to support definitions in shells where the period is a special shell character)

The following options can be used with write to modify the version string in name ID 5:

• --dev - add development status metadata to the version string (mutually exclusive with --rel)
• --rel - add release status metadata to the version string (mutually exclusive with --dev)
• --sha1 - add git commit sha1 short hash state metadata to the version string (requires source under git version control)

Examples

Version string reporting with report

Enter the following to display the head fontRevision version number and name ID 5 font version string for the font Example-Regular.ttf:

$ font-v report Example-Regular.ttf

Include the --dev flag to include the version string (nameID 5) contained in all platformID records:

$ font-v report --dev Example-Regular.ttf

Version number modification with write

The name ID 5 record(s) and head fontRevision record are modified when --ver= is used in your command.

Enter the desired version number in MAJOR.MINOR format after the --ver= flag. Support is provided for the intended period glyph to be replaced in the command with an underscore _ or dash - for users on platforms where the period is a special shell character.

All of the following result in modification of the version number to 2.020:

$ font-v write --ver=2.020 Example-Regular.ttf

$ font-v write --ver=2_020 Example-Regular.ttf

$ font-v write --ver=2-020 Example-Regular.ttf

This request can be combined with other options to include state and status metadata simultaneously.

git SHA1 commit short hash state metadata with write

If your typeface source is under git version control, you can stamp the name ID 5 version string with a short SHA1 hash digest (generally n=7-8 characters, a number that is determined in order to confirm that it represents a unique value for the repository commit) that represents the git commit at the HEAD of the active git branch. The git commit SHA1 hash digest is defined by the git rev-list command at the HEAD of your active repository branch and will match the initial n characters of the git commit SHA1 hash digest that is displayed when you review your git log (or review the commit hashes in the UI of git repository hosting platforms like Github). This is intended to maintain metadata in the font binary about source code state at build time.

Use the --sha1 option with the write subcommand like this:

$ font-v write --sha1 Example-Regular.ttf

The short SHA1 hash digest is added with the following version string formatting:

Version 1.000;[cf8dc25]

This can be combined with other options (e.g. to modify the version number +/- add development or release status metadata) in the same command. Other metadata are maintained and appended to the revised version string in a semicolon delimited format with this modification.

This option does not modify the head fontRevision record.

Add development / release status metadata with write

You can modify the name ID 5 version string to indicate that a build is intended as a development build or release build with the --dev or --rel flag. These are mutually exclusive options. Include only one in your command.

To add development status metadata, use a command like this:

$ font-v write --dev Example-Regular.ttf

and the version string is modified to the following format:

Version 1.000;DEV

To add release status metadata, use a command like this:

$ font-v write --rel Example-Regular.ttf

and the version string is modified with the following format:

Version 1.000;RELEASE

Include the --sha1 flag with either the --dev or --rel flag in the command to include both status and state metadata to the version string:

$ font-v write --sha1 --dev Example-Regular.ttf
$ font-v report Example-Regular.ttf

Example-Regular.ttf:
----- name.ID = 5:
Version 1.000;[cf8dc25]-dev
----- head.fontRevision:
1.000

or

$ git write --sha1 --rel Example-Regular.ttf
$ git report Example-Regular.ttf

Example-Regular.ttf:
----- name.ID = 5:
Version 1.000;[cf8dc25]-release
----- head.fontRevision:
1.000

Any data that followed the original version number substring are maintained and appended after the status metadata in a semicolon delimited format.

These options do not modify the head fontRevision record.

libfv Usage

The libfv Python library exposes the FontVersion object along with an associated set of attributes and public methods for reads, modifications, and writes of the OpenType head fontRevision record version number and the name ID 5 record(s) version string. The font-v executable is built on the public methods available in this library.

Full documentation of the libfv API is available at http://font-v.readthedocs.io/

Import libfv Library into Your Project

To use the libfv library, install the font-v project with the instructions above and import the FontVersion class into your Python script with the following:

from fontv.libfv import FontVersion

Create an Instance of the FontVersion Class

Next, create an instance of the FontVersion class with one of the following approaches:

# Instantiate with a file path to the .ttf or .otf font
fv = FontVersion("path/to/font")

or

# Instantiate with a fontTools TTFont object
#  See the fonttools documentation for details (https://github.com/fonttools/fonttools)
fv = FontVersion(fontToolsTTFont)

The libfv library will automate parsing of the version string to a set of public FontVersion class attributes and expose public methods that you can use to examine and modify the version string. Modified version strings can then be written back out to the font file or to a new font at a different file path.

Note that all modifications to the version string are made in memory. File writes with these modified data occur when the calling code explicitly calls the write method FontVersion.write_version_string() (details are available below).

What You Can Do with the FontVersion Object

Read/write version string

You can examine the full name ID 5 version string and the head fontRevision version number in memory (including after modifications that you make with calling code) with the following:

Get name ID 5 version string (including associated metadata)

fv = FontVersion("path/to/font")
vs = fv.get_name_id5_version_string()

Get head fontRevision version number

fv = FontVersion("path/to/font")
vs = fv.get_head_fontrevision_version_number()

All version modifications with the public methods are made in memory. When you are ready to write them out to a font file, call the following method:

Write version string modifications to font file

fv = FontVersion("path/to/font")
# do things to version string
fv.write_version_string()  # writes to file used to instantiate FontVersion object
fv.write_version_string(fontpath="path/to/differentfont") # writes to a different file path

FontVersion.write_version_string() provides an optional parameter fontpath= that can be used to define a different file path than that which was used to instantiate the FontVersion object.

Compare Version Strings

Test version equality / inequality

Compare name table ID 5 record equality between two fonts:

fv1 = FontVersion("path/to/font1")
fv2 = FontVersion("path/to/font2")

print(fv1 == fv2)
print(fv1 != fv2)

Modify Version String

Some common font version string modification tasks that are supported by the libfv library include the following:

Set version number

Set the version number in the name ID 5 and head fontRevision records:

fv = FontVersion("path/to/font")
fv.set_version_number("1.001")

Set entire version string with associated metadata

Set the full version string in the name ID 5 record. The version number is parsed and used to define the head fontRevision record.

fv = FontVersion("path/to/font")
fv.set_version_string("Version 2.015; my metadata; more metadata")

Work with major/minor version number integers

fv = FontVersion("path/to/font")
# version number = "Version 1.234"
vno = fv.get_version_number_tuple()
print(vno)
>>> (1, 2, 3, 4)
fv2 = FontVersion("path/to/font2")
# version number = "Version 10.234"
vno2 = fv2.get_version_number_tuple()
print(vno2)
>>> (10, 2, 3, 4)

Eliminate all metadata from a version string

Remove all metadata from the version string:

fv = FontVersion("path/to/font")
# pre modification version string = "Version 1.000; some metadata; other metadata"
fv.clear_metadata()
# post modification version string = "Version 1.000"

Set development/release status metadata of the font build

Add a development/release status substring to the name ID 5 record:

fv = FontVersion("path/to/font")
# Label as development build
fv.set_development_status()
# --> adds `DEV` status metadata to version string

# Label as release build
fv.set_release_status()
# --> adds `RELEASE` status metadata to version string

Set git commit SHA1 hash state metadata to maintain documentation of build time source state

Add source code state metadata to the name ID 5 record:

fv = FontVersion("path/to/font")

# Set git commit SHA1 only
fv.set_state_git_commit_sha1()
# --> adds "[sha1 hash]" state metadata to build

# Set git commit SHA1 with development status indicator
fv.set_state_git_commit_sha1(development=True)
# --> adds "[sha1 hash]-dev" state metadata to build

# Set git commit SHA1 with release status indicator
fv.set_state_git_commit_sha1(release=True)
# --> adds "[sha1 hash]-release" state metadata to build

libfv API

Full documentation of the libfv API is available at http://font-v.readthedocs.io/

Contributing to font-v

Source contributions to the libfv library and font-v executable are encouraged and welcomed! Please see the CONTRIBUTING.md documentation for details.

Acknowledgments

Built with the fantastic fonttools and GitPython Python libraries.

License

MIT License