Git for Gentoo developers

Cloning the gentoo.git repository

The ebuild development happens on the official git repository. You can push your changes only through the SSH protocol. Therefore, clone the repository using:

git clone git@git.gentoo.org:repo/gentoo.git

If you do not have SSH access to the Gentoo git service, you can use the anongit mirror for read-only access instead:

git clone https://anongit.gentoo.org/git/repo/gentoo.git

Normally git will fetch the complete history from the start of git repository (Aug 2015). This can require a significant amount of disk space. If you do not need the full history, you can use the --depth option to create a shallow clone, including only a subset containing the the newest commits. For example, --depth=50 will include the 50 newest commits.

Please note that git version 1.9 or newer is required to push when using a shallow clone.

Configuration specific to the Gentoo repository

To ensure that the Gentoo policies are followed, you should set the following configuration variables:

git config --local user.name "${YOUR_FULL_NAME}"
# use your @gentoo.org address even if you have a different default
git config --local user.email "${YOUR_NICKNAME}@gentoo.org"

# enable commit and push signing
git config --local user.signingkey "0x${LONG_OPENPGP_KEY_ID}"
git config --local commit.gpgsign 1
git config --local push.gpgsign 1

# prevent implicit merges on 'git pull'
git config --local pull.ff only

Grafting converted CVS history into the clone

To include the converted CVS history in the git repository, you can graft it into the repository:

git remote add history https://anongit.gentoo.org/git/archive/repo/gentoo-2.git
git fetch history
git replace --graft 56bd759df1d0c750a065b8c845e93d5dfa6b549d cvs-final-2015-08-08

Once this is done, git commands such as git log will include the historical commits after the initial git commit.

Committing and verifying commits

The recommended way of committing to the Gentoo repository is to use pkgdev commit (then pkgdev push). It automatically performs the necessary QA checks on the package being committed and has other features helping with the Gentoo workflow.

For any other use case, git commit and other git commands need to be used. The valid uses of git include:

• creating commits spanning multiple packages and/or multiple areas of the Gentoo repository (eclasses, licenses, profiles…),
• amending a commit created via pkgdev commit with additional files or fixups,
• combining multiple commits created via pkgdev commit using git rebase.

Whenever pkgdev is not used to commit, you need to manually verify all packages affected by the commit using pkgcheck scan --commits. Also, when using git manually, you must perform a manual sign-off to the Certificate of Origin using the -s or --signoff option with your git commit commands. Make sure you have read and understand the actual certificate.

Atomic commits

Whenever possible, use atomic commits. Try to split your changes into logical commits, abiding by the following three rules as much as possible:

1. Do not include multiple irrelevant changes in a single commit. However, make sure not to split relevant changes unnecessarily. For example, if a version bump requires changes in the ebuild, it is correct to perform them in a single commit. However, if you are fixing an additional bug that has been present in the previous version, the fix belongs in a separate commit.
2. Split commits at logical unit boundaries. When updating multiple packages, preferably use a single commit for each package. Avoid combining changes to ebuilds, eclasses, licenses, profiles etc. in a single commit. However, do not split relevant or interdependent changes within a single package.
3. Avoid creating commits introducing a temporary breakage. Unless impossible, add packages in dependency install order. Add licenses before the packages needing them. Commit package.mask and other profile changes before ebuilds relying on them. Usually it is also acceptable to include those changes along with the commit adding the package.

Please note that revision bumps count as side effects of the changes requiring them and do not belong in separate commits. When doing multiple irrelevant changes that require a revision bump, it is only necessary to bump the revision in the first commit in the series introduced by a single push.

Git commit message format

It is important to format the commit messages properly so that they communicate the changes to the reader in a clear and concise way. Additionally, consistency in message format allows for easier parsing by external tools. The first line of the commit message should contain a brief summary of the changes, followed by an empty new line. From the third line onward should be a detailed, multiline explanation of the changes introduced by the commit. At the very end, auxiliary information such as the bugs related to the commit, contributors, and reviewers should be listed using RFC822/git style tags. The sign-off agreement will be added there as well when applied with the commit action. The length of the lines in the message should be 70-75 characters at maximum.

The summary line should start with referencing what is affected by the change followed by a colon ':' character. Use the rules in the following list to determine the proper format based on what has changed, substituting the package, category and eclass names appropriately:

• ${CATEGORY}/${PN}: Single Package (Note that pkgdev commit will automatically insert this for you)
• ${CATEGORY}: Package Category
• profiles: Profile Directory
• ${ECLASS}.eclass: Eclass Directotry
• licenses: Licenses Directory
• metadata: Metadata Directory

For packages where ${CATEGORY}/${PN}: is long, the line length limit can be exceeded, if absolutely necessary, to ensure a more useful summary line. If a commit affects multiple directories, prepend the message with which reflects the intention of the change best. If there are any bugs on Gentoo Bugzilla associated with the commit, the id of the bug can be appended to the summary line using the format #nnnnnn. If you are modifying keywords, clearly state what keywords are added/removed.

For non-trivial commits, the message should contain a detailed explanation of what the commit intends to change, why it is required, and how it is accomplished, along with any other supplementary information.

Finally the commit message should list auxiliary information such as people who are involved in authoring, suggesting, reviewing and testing the changes, and revelant bugs. Use RFC822/git style tags as explained in the Linux Kernel patch guideline. Additionally, the following tags are optionally used in Gentoo:

• Bug: Use this to reference bugs without closing them. The value is a URL to the bug. If multiple bugs need to be referenced, each one should be listed in a separate Bug tag. If a bug on Gentoo Bugzilla, or an issue or a pull request on GitHub is referenced, a reference to the commit will be added automatically.
• Closes: Use this to reference bugs and close them automatically. Alike Bug:, the value is a single URL to the bug, and multiple tags can be used to close multiple bugs. If a bug on Gentoo Bugzilla, or an issue or a pull request on a GitHub repository mirrored by Gentoo is referenced, it will be closed (as fixed) automatically with reference to the commit.

When committing user contributions, make sure to credit them in your commit message with the user's full name and email address. Be aware and respectful of their privacy: some users prefer to be only known by a nickname. Take advantage of tags such as Suggested-by: or Reported-by: when entering such information to the commit message.

An example commit message is shown below:

app-misc/foo: version bump to 0.5

This also adds a new USE flag 'bar' which controls the
new bar functionality introduced with this version.

Bug: https://bugs.gentoo.org/00000
Closes: https://bugs.gentoo.org/00001
Signed-off-by: Alice Bar <a.bar@example.org>