Creating an ebuild repository

From Gentoo Wiki
(Redirected from Custom repository)
Jump to:navigation Jump to:search
This page is a work in progress by kyoreln (talk | contribs). Treat its contents with caution.

Create an ebuild repository to house ebuilds to be made available to Portage for installation. Once an ebuild repository is created, and ebuilds are added to it, it may be shared with others (via a publicly available git repository for example), if it can be of use to others.

Creating ebuild repositories and ebuilds can can be a good way to learn more about the heart of Gentoo. Publishing an ebuild repository can also be a good way to contribute to the community, though helping out with GURU, or becoming a proxy maintainer can be even more helpful. This article will cover all the basics of creating an ebuild repository and maintaining ebuilds in it.

Creating an empty ebuild repository

Using the eselect repository module, it is possible to make an ebuild repository skeleton with just one command:

root #eselect repository create <repository_name>

A new ebuild repository can also be created "by hand", as explained in the Handbook section defining a custom ebuild repository.

Some users will maintain an ebuild repository named "local" for personal things or packages only needed on one machine: eselect repository create local.

Ebuild repositories often get named for the person maintaining them. If creating a repository for publication that is mainly destined to contain a central package with it's dependencies, it may be more helpful to give it a name en rapport with it's contents. The same applies for a repository that will contain packages with usage centered around a particular theme.

Track changes (optional)

Using a Version Control System (VCS) is good practice when creating or maintaining any ebuild repository. Not only will it track changes and allow "undoing" mistakes, among other useful features, it can often make it easier to share an ebuild repository, if or when desired.

Portage has support for several VCSs to automatically provide ebuild repository synchronization, easily sending updates from ebuild repositories that have been made available. Portage supports CVS, git, Mercurial, and Subversion in this fashon. Other VCSs may be used, if an ebuild repository is to provide synchronization by other means, or not at all.


git allows different version branches, which are useful for testing things out, provides easy diff facilities, and other features that can help to create and maintain an ebuild repository.

To start using git to develop an ebuild repository, first initialize the git repository:

user $cd /var/db/repos/local/
root #git init
Initialized empty Git repository in /var/db/repos/local/.git/
root #git add .
root #git commit

Adding an ebuild to an ebuild repository

Now that the basic layout is in order, an ebuild can be added to the ebuild repository.

Of course, a new ebuild repository may be destined to contain newly written ebuilds, but for this example, app-dicts/artha-1.0.2[1] will be used, and it willl be assumed that that ebuild is in the homedir of the user larry, in a file named artha-1.0.2.ebuild.

root #mkdir -p /var/db/repos/local/app-dicts/artha
root #cp ~larry/artha-1.0.2.ebuild /var/db/repos/local/app-dicts/artha/artha-1.0.2.ebuild
root #chown -R portage:portage /var/db/repos/local
root #pushd /var/db/repos/local/app-dicts/artha
root #repoman manifest
root #popd

It should now be possible to install the package from the ebuild repository with the emerge command:

root #emerge --ask --verbose app-dicts/artha

Simple version bump of an ebuild

Sometimes, when a new version comes out upstream, it can be possible to update an ebuild so that it will install the new version, by doing a "simple version bump". If the following are true, an update may be a good candidate to perform a "bump" on:

  • Upstream fixed only minor bugs
  • Dependencies did not change
  • Upstream uses semantic version numbers and changed only the minor number [1]
  • The ebuild file is small and does not use many patches

In the best possible case, it may be feasible to bump just by duplicating the ebuild in an ebuild repository and updating the version number in the filename - but not for an ebuild repository configured to be synced, the changes would be overwritten when syncing.

Version bump of an ebuild in the Gentoo ebuild repository

If a newer version of a package from the Gentoo ebuild repository is available upstream, and the update is small enough to be "bumpable", it is possible to bump it by adding an ebuild to an appropriate ebuild repository configured with Portage. Do not try to bump it directly in the Gentoo ebuild repository files (see next section).

For example, with an ebuild repository named "local", to perform an elementary "bump" to a newer version of app-emulation/docker from the Gentoo ebuild repository.

user $mkdir -v /var/db/repos/local/app-emulation
user $cd /var/db/repos/local/app-emulation
user $cp -r /var/db/repos/gentoo/app-emulation/docker .
user $cd docker/
user $cp docker-1.11.0.ebuild docker-1.12.6.ebuild
user $repoman --digest=y -d full

Now test the installation:

root #emerge --ask =app-emulation/docker-1.12.6

Finished ebuilds should be added to the version control system, to make the updated ebuild available to others. If using an ebuild repository from GitHub, consider adding a pull request.

Avoid direct version bumps

It may be tempting to just rename an ebuild to a new version inside the local Gentoo ebuild repository files, when it is possible to bump an ebuild in such a way, but this has inconveniences and should not be done. This method is sometimes brought up and suggested, however it will have undesirable consequences:

  • All changes get lost on the next sync of the Gentoo ebuild repository (unless sync-type git is in use, in that case a topic branch could be used)
  • User contributions should be separated from the Gentoo ebuild repository

Do not do this:

root # # cd /var/db/repos/gentoo/app-emulation/docker
root # # cp docker-1.11.0 docker-1.12.6
root # # repoman --digest=y -d full


Use repoman's functions to act on an ebuild repository, all while enforcing a minimal level of quality in the changes to ebuilds and related metadata, and to perform checks.

The ebuild command can still be used to generate manifest/digest files, however it does not include any of the other quality assurance benefits (such as debug output) included with repoman:

root #ebuild foo.ebuild digest
>>> Creating Manifest for /var/db/repos/local/bar/foo

See also


  • Section on methods to share an ebuild repository (github, rsync...) / how to provide synchronization for an ebuild repository that has been shared.
  • Section on how to register an ebuild repository on r.g.o.


  1. one example of semantic version number is described on