Custom repositories are handled the same way as the standard repository /var/db/repos/gentoo. The repository configuration is in the directory /etc/portage/repos.conf

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 repository copy in /var/db/repos with all the ebuilds. eselect repository list -i will then confirm that it is installed and in use

There is eselect repository disable linursoverlay and eselect repository enable linursoverlay

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

eselect repository remove <overlay repository name> to remove

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 the console know it:

source /etc/portage/make.conf

And verify the result:

echo $PORTDIR_OVERLAY

Now work in this console with the 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 /var/db/repos/gentoo/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>.