Git for Gentoo developers
This guide covers git usage instructions and policies specific to Gentoo ebuild development. It assumes that the readers possess basic git knowledge. For a generic guide, please see the official git book.
Preparing a development checkout
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 [email protected]: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 to gentoo.git
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
usinggit 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:
- 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.
- 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.
-
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 thatpkgdev 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.
#
are considered to be comments
by git and not included in the commit message. Make sure that a new
line does not start with #nnnnnn
. Optionally, git can be
configured to use a different character for comments by changing the
commentchar
option.
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 separateBug
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. AlikeBug:
, 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 <[email protected]>