Standard git workflow

From Gentoo Wiki
Jump to:navigation Jump to:search

Attempt at describing a modern git workflow with pkgcheck and pkgdev.

This tries to be an alternative to the Gentoo git workflow page which acts as more of a reference than a guide or tutorial.


The previous tooling, repoman, handled both QA scanning as well as acting as a commit helper.

The new workflow is split into two major components:

  1. scanning for QA issues (pkgcheck)
  2. committing the changes (pkgdev, or the far more spartan pkgcommit if desired)

First, install these essential tools:

root #emerge --ask dev-util/pkgcheck dev-util/pkgdev

Optionally, install these bits:

  • app-portage/mgorny-dev-scripts for additional helpers like pkgdiff to diff (build system) changes between versions. Their use is optional but it's worth reading over the list available.
  • app-portage/iwdevtools for file diff (compare old/new, check if e.g. files now missing), rcd helper to navigate packages, detecting missing dependencies via ELF NEEDED, etc
root #emerge --ask app-portage/mgorny-dev-scripts app-portage/iwdevtools

Checking for issues

pkgcheck is a QA scanning tool equivalent to the "check" part of repoman. Its main use is pkgcheck scan (equivalent to repoman full -dx).

See pkgcheck#Examples.

Committing changes


pkgdev is a commit helper, equivalent to the "commit" part of repoman.

Its main uses are:

  • pkgdev commit (equivalent to repoman commit), and
  • pkgdev manifest (equivalent to repoman manifest)

See pkgdev#Examples.


pkgcommit is a helper tool from app-portage/mgorny-dev-scripts. It is not part of the pkgcore suite. It just generates the commit summary based on the current directory (no "smart generation" based on the actual changes like pkgdev).


The overall method is always the same:

  1. Enter a repository
  2. Navigate to a package (using app-misc/scrub as an example)
  3. Make some changes
  4. Run pkgdev commit (recommended) or alternatively pkgcommit

Bumping app-misc/scrub

Using app-portage/iwdevtools, a shortcut tool rcd can be used to quickly jump to a package.

This example uses pkgdev. When calling pkgdev commit, it calls pkgcheck scan automatically.

First, enter the repository the old fashioned way:

user $cd ~/git/gentoo/app-misc/scrub

Or alternatively if using app-portage/iwdevtools:

user $rcd scrub

Install the dependencies of the package:

root #emerge -av1o --with-test-deps app-misc/scrub

Copy the old ebuild as a basis for new changes and regenerate the Manifest:

user $cp scrub-2.6.0.ebuild scrub-2.6.1.ebuild
user $pkgdev manifest

Go read the upstream release notes! Then compare the build system changes using pkgdiff -b from app-portage/mgorny-dev-scripts.

user $pkgdiff -b scrub-2.6.0.ebuild scrub-2.6.1.ebuild

Adapt the ebuild as needed:

user $$EDITOR scrub-2.6.1.ebuild

Optionally run pkgcheck scan to check for QA issues during the work/change process:

user $pkgcheck scan

Test it out (repeat as necessary):

user $ebuild scrub-2.6.1.ebuild clean test install merge

Try running the tool too (ideally use it):

user $scrub --version
scrub version 2.6.1

Commit the changes once ready (note that the command from the commit command shows pkgcheck scan results):

user $git add scrub-2.6.1.ebuild && pkgdev commit
  DeprecatedEapi: version 2.6.0: uses deprecated EAPI 6
  RedundantVersion: version 2.6.0: slot(0) keywords are overshadowed by version: 2.6.1
[master 65b81235dc06d] app-misc/scrub: add 2.6.1
 2 files changed, 17 insertions(+)
 create mode 100644 app-misc/scrub/scrub-2.6.1.ebuild

Bumping app-misc/scrub without pkgdev

mgorny describes on his blog an alternative workflow (from before pkgdev was created) based on pkgcommit and pkgcheck scan --commits.

It can be roughly summarized as:

  1. Make changes
  2. pkgcommit
  3. pkgcheck scan --commits
  4. Make changes based on pkgcheck output
  5. git-fixup
  6. pkgcheck scan --commits
  7. ...
  8. Once done, git rebase -i --autosquash

See Also

  • Gentoo git workflow — outlines some rules and best-practices regarding the typical workflow for ebuild developers using git.
  • Pkgcheck — a pkgcore-based QA utility for ebuild repos.
  • Pkgdev — a collection of tools for Gentoo development.

External resources