Project:Toolchain/Patchsets with Git

From Gentoo Wiki
Jump to:navigation Jump to:search
Warning, this page is a work in progress by dilfridge (talk | contribs). Treat its contents with caution.

This page describes in detail how the sys-libs/glibc patchsets have been migrated to Git. Hopefully we'll at some point use the same or a very similar system for all parts of toolchain (ie., gcc, binutils, ...).


Regular upstream development

The libc git repository has a master branch where current development takes place. On this master branch, releases are tagged as, e.g, glibc-2.26. From each release tag, a stable / backport branch starts with name release/2.26/master.

Upstream git repository: git://

Vendor branches and tags

The Gentoo-specific branches and tags are maintained in a repository on Gentoo infrastructure:

Gentoo has a vendor branch gentoo/2.31, which branches off at the upstream glibc-2.31 tag. On this branch the commits corresponding to Gentoo ebuild releases are tagged as gentoo/glibc-2.31-0, where in this case 0 is the patchset number. When upstream makes a new release, say glibc-2.32, a new such branch gentoo/2.32 shall be created starting at that tag (see below for the procedure).

Setting yourself up for development basically means

user $cd ~/Gentoo/misc/
user $cd glibc
user $git remote add gentoo git+ssh://
user $git fetch gentoo
user $git checkout gentoo/2.31

Adding patches to a release branch

Adding patches is easy; just add commits to one of our vendor branches as e.g. gentoo/2.31.

Usually they should be cherry-picked from the upstream stable branch release/2.31/master or the upstream development branch master. In rare cases it may also make sense to add more Gentoo-specific stuff.

Please only add commits to the gentoo/* vendor branches, never rebase or force-push them! Also, the gentoo/* vendor branches must have a linear history, i.e. no merge commits, otherwise the patchset generation may fail.

Adding patches for git master

There is a small set of Gentoo-specific patches that is added to each new glibc release. These are maintained in a separate git repo, together with the patchset generation script.

user $cd ~/Gentoo/misc/

All patches in the patches/ subdirectory are supposed to be applied in numerical order (and are automatically applied such by the glibc-9999 ebuild).

If you want to modify the base Gentoo patchset, here's the place to do that.

Making a patchset for use in an ebuild

user $cd ~/Gentoo/misc/glibc
user $git checkout gentoo/2.31
user $~/Gentoo/misc/glibc-patches/ 2.31 7

This generates from the current head of gentoo/2.31 a patchset tarball named glibc-2.31-patches-7.tar.xz, and tags the current head of gentoo/2.31 as gentoo/glibc-2.31-7.

  • Please read the script before using it!
  • Make sure your gpg is working for the signed tag!
  • Any commit where the commit message starts with [no-patch] will not generate a patch.
  • Uploading the tarball and pushing stuff to git still must be done manually.
  • This description is correct for the glibc-2.31 branch and later.




  • The upstream release branch is usually named as binutils-2_29-branch
  • The upstream release tags usually looks like binutils_2_29_1
  • The Gentoo branches are named gentoo/binutils-2.29.1 (since we might one day also make patchsets for gdb)
  • The Gentoo patchset tags look like gentoo/binutils-2.29.1-2
  • Since there are irregularities in the release tag naming, you can override them by creating a tag gentoo/binutils-2.29.1-upstream and that will be used as reference for the tarball instead.


Gentoo branches are occasionally rebased on top of upstream branches. Gentoo-specific patches contain "Gentoo: " prefix. Gentoo patches are initially maintained in gentoo/binutils-9999 branch and later cherry-picked into release branches.


  • Upstream pushes a daily automated commit onto each branch, increasing the date in a file. sskips date bumping patches when tarball is done. This eases patch rebasing.
  • The "development flag" is a variable set to "true" in git and to "false" in tarballs. Since occasionally patches touch that (while not yet released), we add a patch 0000-... that makes it true, and a patch 9999-... that makes it false again... We definitely do not want it true since it adds -Werror and makes the soversion of libbfd contain the date.

How to cut a new patchset

To create new branch and cut first patchset you need to:

  • create a new gentoo granch based on upstream branch
  • apply gentoo-specific patches on top (usually from gentoo/binutils-9999 branch).
  • tag and tarball
  • push tags and branches

Example session:

user $git checkout -b gentoo/binutils-2.32 origin/binutils-2_32-branch
user $git cherry-pick origin/master..gentoo/binutils-9999
user $./scripts/gentoo/ 2.32 1
user $git push gentoo gentoo/binutils-2.32:gentoo/binutils-2.32
user $git push --tags gentoo

To cut new patchset on existing branch you need to:

  • [optional] rebase gentoo-specific branch on top of upstream branch to pull in fresh patches
  • apply new gentoo-specific patches (or cherry-pick from gentoo/binutils-9999 anew)
  • tag and tarball.
  • push tags and branches

Example session: TODO


Gentoo's gcc patches live at

These are just versioned contents normally seen files/ subtree.

adding new patch

Every Gentoo developer has access to push patches to the patch tree.

  • drop a patch to versioned directory, like 8.2.0/gentoo/
  • add an entry to README.history, like 8.2.0/gentoo/README.history
  • [optionally] cut new patchset with

See README files for more details.