To be more open, overlays can be handled exactly the same way as /usr/portage using the repository configuration found in /etc/portage/repos.conf. As example and consequence the file gentoo.conf holds all necessary to get the the standard gentoo ebuilds.

Instead adding manually a config file emerge eselect-repository

eselect repository add linursoverlay git https://github.com/linurs/linursoverlay.git creates then a config file eselect-repo.conf that holds all necessary to find as example the linursoverlay from GitHub. It creates the local copy in /var/db/repos

emerge --sync or faster emerge --sync linursoverlay will then get the updates

Local overlays are mainly used to develop ebuilds.

Create a local overlay directory where the collection of ebuilds go:

mkdir<path to overlay directory>>

Tell /etc/portage/make.conf where it is by adding the following line

PORTDIR_OVERLAY="<path to first overlay directory> <path to second overlay directory>"

Now additional sub-directories serving as categories (as app-editors) can be created there where the ebuilds to be developed can be put.

Now let your console know what you did:

source /etc/portage/make.conf

And verify the result:

echo $PORTDIR_OVERLAY

Now you can work in this console with your local overlay. Since every process has it own environmental variables, just this console and its children will have the PORTDIR_OVERLAY variable updated.

The tool layman (emerge layman) handles overlays via expanding the PORTDIR_OVERLAY variable. layman can be considered outdated since adding repositories is the new way.

To see what overlays layman can get

layman -L

To add a single overlay out of the list of available overlays:

layman -a<overlay-name>

As example layman -a sunrise

To see what overlays you have installed

layman -l

To de-install

layman -d <overlay-name>

To install a package from the overlay (= ebuild)

emerge -av<category>/<package>

To update the overlays

layman -s <overlay name>

or

layman -s ALL

or

layman -S

layman creates a cache under /var/lib/layman

/etc/layman/layman.cfg is the configuration file.

Overlays can be put in GitHub and therefore be used by many computers.

A GitHub account is required that has a name. GitHub uses also the term repository to hold the files. A GitHub repository needs therefore to be created that holds the overlay or repository.

In this GitHub repository the the required ebuilds need to be put. Take an already existing overlay as example and create a directory with the ebuilds and the metadata and profiles directory.

Inside this directory add a repository.xml file needs to be added that holds all the necessary data about the overlay/repository.

<?xml version="1.0" encoding="UTF-8"?>
<!DOCTYPE repositories SYSTEM "/dtd/repositories.dtd">
<repositories xmlns="" version="1.0">
<repo quality="experimental" status="unofficial">
    <name>linursoverlay</name>
    <description>
      experimental ebuilds from linurs.org
    </description>
    <homepage>
      https://github.com/linurs/linursoverlay
    </homepage>
    <owner type="person">
        <email>urs@linurs.org</email>
        <name>Urs Lindegger</name>
    </owner>
    <source type="git">
       git://github.com/linurs/linursoverlay.git
    </source>
    <source type="git">
       https://github.com/linurs/linursoverlay.git
    </source>
  </repo>
</repositories>

To update it follow the GitHub rules and create a branch, so master branch stays intact for all the other users. When done create a pull request followed by a merge to the master.

The GitHub repository can be added to a Gentoo system as repositories or the old way as overlays.

xmllint --noout --schema $(portageq get_repo_path / gentoo)/metadata/xml-schema/repositories.xsd repositories.xml or

xmllint --noout --schema /usr/portage/metadata/xml-schema/repositories.xsd repositories.xml

verifies the repositories.xml file. See for other things missing: https://wiki.gentoo.org/wiki/Project:Overlays/Overlays_guide

to clone it git clone https://github.com/gentoo/api-gentoo-org.git

cd api-gentoo-org/

Add the repository to files/overlay/repositories.xml and then the tricky authorization part starts to push it back and make a pull request.

Commands as emerge --search, esearch or gui programs as porthole will find the ebuilds in the installed overlays. However there are many overlays not installed and it makes no sense to install all available overlays just to look for an ebuild that might or not might be there. To get a tool that can search in not installed overlays emerge eix

eix is much more than just an overlay search tool, it is an alternative to various gentoo tools. Therefore it has a

There is a huge list of options as man eix shows. eix-update will update is cache containing portage and the installed overlays.

The command eix-remote update will download the /var/cache/eix/remote.tar.bz2 file and than unpack it, it is quite common that this file has a newer version than eix being used and then fails. In this case simply update eix to the newest version.

Per default eix-update will rewrite the cache and therefore delete what eix-remote update added. To avoid that a variable needs to be set check if eix --dump | grep KEEP_VIRTUALS. As default it reports false, so the following needs to be added to /etc/eixrc then it has to be added

KEEP_VIRTUALS="true"

Finally to look for a ebuild type eix<ebuildname>.