Portage - Multiple Repository Support - Getting Started

1 - Multiple Repositories

1.1 - Adding repositories

In portage-multirepo it's possible to set and config repositories in repos.conf file. The file syntax is similar of sets.conf file. Each section contains configuration for one repository. 
There are 3 constants that can be used:
LOCATION: Shows where in disk the repository is located. This constant is mandatory.
PRIORITY: Has the priority of this repository. Portage will look for repositories with lower priorities first.
SYNC: The sync url for this repository. It's necessary to write in the url the Control Version System used to sync. If you want to download from http://server/repo.git you should use git+http://server/repo.git as the url.
The name of the repository will be read from profile/repo_name file, in LOCATION. If this is diferent than the name of the section(inside []) the name in repo_name will be used.
There is a section DEFAULT, where user can set the main-repo. It's mandatory to have a main-repo if PORTDIR variable is empty. 

Ex:
[DEFAUL]
main-repo=name_of_the_repository
[name_of_the_repository]
LOCATION=/usr/local/portage
PRIORITY=3
SYNC=git://server/repo.git

1.2 - Repostories and Overlays

Portdir and its overlays are all handled as repositories. If PORTDIR and SYNC constants are used in make.conf (or make.conf.global) portage will create a repository with correct LOCATION and SYNC constants and PRIORITY=1000. There will be created repositories for each overlay in PORTDIR_OVERLAY too. The Priorities are set from 1 to 1000. So overlays will have lower priorities than portdir, so will overwrite portdir, like the original portage. Other repositories can be set in repos.conf, without any problem. If main-repo constant in DEFAULT section is not set, the repository in PORTDIR will be used as main-repo.
It's possible to change Portdir's and overlays' configuration using repos.conf file. Changes in repos.conf will overwrite the config in this constants. So it's possible to change SYNC variable from portdir just adding the following lines to repos.conf file.

[gentoo]
SYNC=another_url

It's also possible to change main-repo in DEFAUL section, adding SYNC url to any overlay and changing their priorities. 

1.3 - Old repos.conf file
All features from old repos.conf file are stil working. You can check them in: http://dev.gentoo.org/~zmedico/portage/doc/man/portage.5.html

2.0 - Using repo_name in deps
It's now possible to use the repository name in emerge when writing a dependency. Just place it at the end (but before useflags) separated by :: . Running emerge package::local_repo will look for package only in repository named 'local_repo'. Full atom name will be somethink like app-portage/genlop-0.30.7:0::gentoo[bash-completion].
Here we got there are some examples:
emerge genlop::gentoo # installs genlop from gentoo repository (usually portage tree)
emerge genlop --exclude app-portage/genlop::gentoo #installs genlop from any repository, except gentoo
emerge genlop::sunrise #tries installs genlop from sunrises repository (it will fail, because genlop is not in sunrise)

We can also use the same syntax in /etc/portage/package.* files.
If we write in package.mask file the following lines:
app-portage/genlop::local_repository
Genlop from local_repository(and only from local_repository) will be masked.

Unfortunately wildcards are not yet supported. :( So something like */genlop::gentoo won't work.

3.0 - Syncing
3.1 - Using other Version Control Systems to sync repositories
It's possible to use git, bzr, mercurial, darcs, svn, cvs, rsync and a tarball over http to sync repositories. emerge will find out what cvs should it use looking in the url. So it's important to inform this in the url. If you will use any cvs over http, ssh or other repository you should write the cvs name and a plus sign before the protocol name. Following there are some examples of urls:
SYNC=svn+http://overlays.gentoo.org/proj/sunrise
SYNC=git://git.overlays.gentoo.org/proj/kde.git
SYNC=git+http://github.com/belak/gentoo.overlay
SYNC=git+ssh://git@git.overlays.gentoo.org/user/alexcepoi.git
SYNC=darcs+http://code.haskell.org/gentoo/gentoo-haskell/
SYNC=bzr+https://launchpad.net/bzr-gentoo-overlay/