Repository format/metadata/layout.conf

From Gentoo Wiki
Jump to:navigation Jump to:search

The metadata/layout.conf file is a file describing global properties of a repository.

Its behaviour is defined by GLEP 82. Implementations may implement extensions but these cannot be relied upon by ebuilds or repositories wishing to be portable.

File format

  • The file consists of a number of key-value pairs, one pair per line, with the two separated by = (equal sign).
  • Comment lines start with #.
FILE metadata/layout.confAn example showing the format of the file
key1 = value1
# comment
key2 = value2

Possible keys

This page contains only some of the possible keys and values in layout.conf.

For a thorough listing, refer to:

  • GLEP 82 (authoritative)
  • the Portage manual: man 5 portage


Use of this property is discouraged. Use profiles/repo_name instead.

This setting specifies the name of the repository. It takes precedence over an existing value in profiles/repo_name:

FILE metadata/layout.confSpecifies repository name
repo-name = foo-overlay


Allows multiple names (separate from the primary name, see repo-name) to be used to reference the repository. Unset by default. Space-separated.

FILE metadata/layout.confSpecifies repository aliases
# gen2 is a fork of Gentoo that can be used in place of the Gentoo
# repository
repo-name = gen2
aliases = gentoo


This property is mandatory.

The masters key specifies a list of master repositories for this particular repository. Whenever installing an ebuild from the particular repository, the package manager can use ebuilds, eclasses, and (depending on the repository format used) profiles from one or more master repositories.

The most common example is a repository (overlay) which provides additional packages for Gentoo. Such a package uses resources from the gentoo ebuild repository:

FILE metadata/layout.confAn example for repository relying on gentoo ebuild repository ebuilds, eclasses, and possibly profiles
masters = gentoo

A particular repository may have more than a single masters entry. These are not inherited over repositories. In the following example, everything from gentoo take precedence over everything in python that shares the same name:

FILE metadata/layout.confAn example for repository relying on two other repositories
masters = python gentoo

Finally, a stand-alone repository like gentoo should provide an empty masters list. This means that all ebuilds (dependencies), eclasses, and so on in that repository must be found in that repository:

FILE metadata/layout.confAn example for a stand-alone repository
masters =


This setting bans EAPIs (repoman will fail):

FILE metadata/layout.confBans EAPI 0 and EAPI 1
eapis-banned = 0 1


Similar to eapis-banned but for the EAPI used in profiles.


This setting marks EAPIs as deprecated (repoman will prompt a warning):

FILE metadata/layout.confMarks EAPI 2 and EAPI 3 as deprecated
eapis-deprecated = 2 3


Similar to eapis-deprecated but for the EAPI used in profiles.


If enabled, the commits made in this repository will be signed:

FILE metadata/layout.confEnabling commit signing
sign-commits = true

This applies only to git repositories. It requires git 1.7.9 or newer.

The key used to sign commits can be set through:

user $git config user.signingkey <keyid>


It's recommended to leave this and manifest-required-hashes unset to roll with the defaults in Gentoo.

See Repository format/package/Manifest too.

Tools will support these hash algorithms when reading and creating Manifests for ebuilds. They may use a subset if some are unrecognized or not supported. Space-separated.

The default is implementation-defined.

FILE metadata/layout.confDefining hashes used for Manifests
manifest-hashes = BLAKE2B SHA512


This defines the list of hashes which must be present in a Manifest. Tools must regenerate (and refetch if required) Manifests if these hashes are not present.

FILE metadata/layout.confDefining mandatory hashes used for Manifests
# Allow using BLAKE2B and/or SHA512
manifest-hashes = BLAKE2B SHA512

# But require BLAKE2B to be present at least
# If unset, would require both BLAKE2B and SHA512.
manifest-required-hashes = BLAKE2B


Enabled by default. If enabled, the manifest files will be signed whenever committing to this repository from a GPG-enabled client:

FILE metadata/layout.confDisabling Manifest signing
sign-manifests = false

In Portage, the manifest signing is enabled by adding sign to the FEATURES variable in /etc/portage/make.conf.


Disabled by default. If enabled, thin manifests will be used inside the repository instead of the regular manifests:

FILE metadata/layout.confEnabling thin Manifests
thin-manifests = true

Repositories using thin-manifests will have only DIST entries in their Manifests.


Strict by default. Enforces a correct manifest for each package:

FILE metadata/layout.confEnforce correct manifests
use-manifests = strict

Possible values are:

  • strict to enforce manifest usage;
  • true to allow and create Manifests, but mismatches are ignored;
  • false to disable manifest usage.


Controls whether tools should write a ChangeLog. false by default.

FILE metadata/layout.confEnabling ChangeLogs
# Note that this is OFF by default.
update-changelog = true


Controls cache formats used by the repository. Default is implementation-defined.

FILE metadata/layout.confCache format
# Modern repo
cache-formats = md5-dict
# Backwards compatibility case (very old versions of Portage, <2.2.0_alpha68)
cache-formats = md5-dict pms


Control functionality available to profiles in this repo such as which files may be dirs, or the syntax available in parent files. Use portage-2 if unsure. Default is portage-1-compat even though it is invalid to set this manually.

FILE metadata/layout.confUse repository relative profile paths
profile-formats = portage-2

Possible values are pms portage-1 portage-2 profile-bashrcs profile-set profile-default-eapi build-id, and profile-repo-deps. Multiple options can be set (space-separated).

  • pms is the format specified in PMS which has no extensions: the Portage extensions below exist to supplement functionality in this base specification
  • portage-1 indicates that this repo contains profiles that may use directories for USE and mask configuration instead of just files
  • portage-2 indicate that paths such as gentoo:targets/desktop or :targets/desktop in profile parent files can be used to express paths relative to the root profiles directory of a repository
  • profile-bashrcs enables the per-profile bashrc mechanism package.bashrc
  • profile-set enables support for using the profile packages file to add atoms to the @profile package set
  • profile-default-eapi enables support for the profile_eapi_when_unspecified attribute of layout.conf
  • build-id allows dependency atoms in the profile to refer to specific builds (see the binpkg-multi-instance FEATURES setting in make.conf(5)). A build-id atom is identical to a version-specific atom, except that the version is followed by a hyphen and an integer build-id
  • profile-repo-deps allows dependency atoms in the profile to refer to specific repositories


Controls the list of PROPERTIES tokens/values which are permitted for ebuilds within the repository. If set, development tools will warn on tokens in ebuilds which are not listed. If unset, all tokens are permitted.

FILE metadata/layout.confAllow PROPERTIES=live
properties-allowed = live


Controls the list of RESTRICT tokens/values which are permitted for ebuilds within the repository. If set, development tools will warn on tokens in ebuilds which are not listed. If unset, all tokens are permitted.

FILE metadata/layout.confAllow RESTRICT=primaryuri
restrict-allowed = primaryuri

External resources