Awesome
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 using1.000
,1_000
or1-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.