Title:Manifest2 format
Last-Modified:2006/01/23 10:24:24
Author:Marius Mauch <genone at>,
Type:Standards Track
Post-History:06-Dec-2005, 23-Jan-2006



This GLEP proposes a new format for the Portage Manifest and digest file system by unifying both filetypes into one to improve functional and non-functional aspects of the Portage Tree.


Please see [1] for a general overview. The main long term goals of this proposal are to:


The new Manifest format would change the existing format in the following ways:

Each line in the new format has the following format:

<filetype> <filename> <filesize> <chksumtype1> <chksum1> ... <chksumtypen> <chksumn>

However theses entries will be stored in the existing Manifest files.

An actual example [6] for a (pure) Manifest2 file..

Compability Entries

To maintain compability with existing portage versions a transition period after is the introduction of the Manifest2 format is required during which portage will not only have to be capable of using existing Manifest and digest files but also generate them in addition to the new entries. Fortunately this can be accomplished by simply mixing old and new style entries in one file for the Manifest files, existing portage versions will simply ignore the new style entries. For the digest files there are no new entries to care about.


It is important to note that this proposal only deals with a change of the format of the digest and Manifest system.

It does not expand the scope of it to cover eclasses, profiles or anything else not already covered by the Manifest system, it also doesn't affect the Manifest signing efforts in any way (though the implementations of both might be coupled).

Also while multiple hash functions will become standard with the proposed implementation they are not a specific feature of this format [2].

Number of hashes

While using multiple hashes for each file is a major feature of this proposal we have to make sure that the number of hashes listed is limited to avoid an explosion of the Manifest size that would revert the main benefit of this proposal (reduzing tree size). Therefore the number of hashes that will be generated will be limited to three different hash functions. For compability though we have to rely on at least one hash function to always be present, this proposal suggest to use SHA1 for this purpose (as it is supposed to be more secure than MD5 and currently only SHA1 and MD5 are directly available in python, also MD5 doesn't have any benefit in terms of compability).


The main goals of the proposal have been listed in the Motivation, here now the explanation why they are improvements and how the proposed format will accomplish them.

Removal of digest files

Normal users that don't use a "tuned" filesystem for the portage tree are wasting several dozen to a few hundred megabytes of disk space with the current system, largely caused by the digest files. This is due to the filesystem overhead present in most filesystem that have a standard blocksize of four kilobytes while most digest files are under one kilobyte in size, so this results in approximately a waste of three kilobytes per digest file (likely even more). At the time of this writing the tree contains roughly 22.000 digest files, so the overall waste caused by digest files is estimated at about 70-100 megabytes. Furthermore it is assumed that this will also reduce the disk space wasted by the Manifest files as they now contain more content, but this hasn't been verified yet.

By unifying the digest files with the Manifest these tiny files are eliminated (in the long run), reducing the apparent tree size by about 20%, benefitting both users and the Gentoo infrastructure.

Reducing redundancy

When multiple hashes are used with the current system both the filename and filesize are repeated for every checksum type used as each checksum is standalone. However this doesn't add any functionality and is therefore useless, so the new format removes this redundancy. This is a theoretical improvement at this moment as only one hash function is in use, but expected to change soon (see [2]).

Removal of checksum collisions

The current system theoretically allows for a DIST type file to be recorded in multiple digest files with different sizes and/or checksums. In such a case one version of a package would report a checksum violation while another one would not. This could create confusion and uncertainity among users. So far this case hasn't been observed, but it can't be ruled out with the existing system. As the new format lists each file exactly once this would be no longer possible.

Flexible verification system

Right now portage verifies the checksum of every file listed in the Manifest before using any file of the package and all DIST files of an ebuild before using that ebuild. This is unnecessary in many cases:

Backwards Compatibility

Switching the Manifest system is a task that will need a long transition period like most changes affecting both portage and the tree. In this case the implementation will be rolled out in several phases:

  1. Add support for verification of Manifest2 entries in portage
  2. Enable generation of Manifest2 entries in addition to the current system
  3. Ignore digests during emerge --sync to get the size-benefit clientside. This step may be ommitted if the following steps are expected to follow soon.
  4. Disable generation of entries for the current system
  5. Remove all traces of the current system from the tree (serverside)

Each step has its own issues. While 1) and 2) can be implemented without any compability problems all later steps have a major impact:

Another problem is that some steps affect different targets:

While it is relatively easy to get all devs to use a new portage version this is practically impossible with users as some don't update their systems regulary. While six months are probably sufficient to reach a 95% coverage one year is estimated to reach an almost-complete coverage. All times are relative to the stable-marking of a compatible portage version.

No timeframe for implementation is presented here as it is highly dependent on the completion of each step.

In summary it can be said that while a full conversion will take over a year to be completed due to compability issues mentioned above some benefits of the system can selectively be used as soon as step 2) is completed.

Other problems

Impacts on infrastructure

While one long term goal of this proposal is to reduce the size of the tree and therefore make life for the Gentoo Infrastructure easier this will only take effect once the implementation is rolled out completely. In the meantime however it will increase the tree size due to keeping checksums in both formats. It's not possible to give a usable estimate on the degree of the increase as it depends on many variables such as the exact implementation timeframe, propagation of Manifest2 capable portage versions among devs or the update rate of the tree. It has been suggested that Manifest files that are not gpg signed could be mass converted in one step, this could certainly help but only to some degree (according to a recent research [3] about 40% of all Manifests in the tree are signed, but this number hasn't been verified).

Reference Implementation

A patch for a prototype implementation of Manifest2 verification and partial generation has been posted at [4], it will be reworked before being considered for inclusion in portage. However it shows that adding support for verification is quite simple, but generation is a bit tricky and will therefore be implemented later.


Some things have been considered for this GLEP but aren't part of the proposal yet for various reasons:


Thanks to the following persons for their input on or related to this GLEP (even though they might not have known it): Ned Ludd (solar), Brian Harring (ferringb), Jason Stubbs (jstubbs), Robin H. Johnson (robbat2), Aron Griffis (agriffis)

Also thanks to Nicholas Jones (carpaski) to make the current Manifest system resistent enough to be able to handle this change without too many transition problems.


[2](1, 2)
[3]gentoo-core mailing list, topic "Gentoo key signing practices and official Gentoo keyring", Message-ID <>