What is a patch?¶

A patch is a small text document containing a delta of changes between twodifferent versions of a source tree. Patches are created with thediffprogram.

To correctly apply a patch you need to know what base it was generated fromand what new version the patch will change the source tree into. Theseshould both be present in the patch file metadata or be possible to deducefrom the filename.

How do I apply or revert a patch?¶

You apply a patch with thepatch program. The patch program reads a diff(or patch) file and makes the changes to the source tree described in it.

Patches for the Linux kernel are generated relative to the parent directoryholding the kernel source dir.

This means that paths to files inside the patch file contain the name of thekernel source directories it was generated against (or some other directorynames like “a/” and “b/”).

Since this is unlikely to match the name of the kernel source dir on yourlocal machine (but is often useful info to see what version an otherwiseunlabeled patch was generated against) you should change into your kernelsource directory and then strip the first element of the path from filenamesin the patch file when applying it (the-p1 argument topatch doesthis).

To revert a previously applied patch, use the -R argument to patch.So, if you applied a patch like this:

patch -p1 < ../patch-x.y.z

You can revert (undo) it like this:

patch -R -p1 < ../patch-x.y.z

How do I feed a patch/diff file topatch?¶

This (as usual with Linux and other UNIX like operating systems) can bedone in several different ways.

In all the examples below I feed the file (in uncompressed form) to patchvia stdin using the following syntax:

patch -p1 < path/to/patch-x.y.z

If you just want to be able to follow the examples below and don’t want toknow of more than one way to use patch, then you can stop reading thissection here.

Patch can also get the name of the file to use via the -i argument, likethis:

patch -p1 -i path/to/patch-x.y.z

If your patch file is compressed with gzip or xz and you don’t want touncompress it before applying it, then you can feed it to patch like thisinstead:

xzcat path/to/patch-x.y.z.xz | patch -p1bzcat path/to/patch-x.y.z.gz | patch -p1

If you wish to uncompress the patch file by hand first before applying it(what I assume you’ve done in the examples below), then you simply rungunzip or xz on the file -- like this:

gunzip patch-x.y.z.gzxz -d patch-x.y.z.xz

Which will leave you with a plain text patch-x.y.z file that you can feed topatch via stdin or the-i argument, as you prefer.

A few other nice arguments for patch are-s which causes patch to be silentexcept for errors which is nice to prevent errors from scrolling out of thescreen too fast, and--dry-run which causes patch to just print a listing ofwhat would happen, but doesn’t actually make any changes. Finally--verbosetells patch to print more information about the work being done.

Common errors when patching¶

When patch applies a patch file it attempts to verify the sanity of thefile in different ways.

Checking that the file looks like a valid patch file and checking the codearound the bits being modified matches the context provided in the patch arejust two of the basic sanity checks patch does.

If patch encounters something that doesn’t look quite right it has twooptions. It can either refuse to apply the changes and abort or it can tryto find a way to make the patch apply with a few minor changes.

One example of something that’s not ‘quite right’ that patch will attempt tofix up is if all the context matches, the lines being changed match, but theline numbers are different. This can happen, for example, if the patch makesa change in the middle of the file but for some reasons a few lines havebeen added or removed near the beginning of the file. In that caseeverything looks good it has just moved up or down a bit, and patch willusually adjust the line numbers and apply the patch.

Whenever patch applies a patch that it had to modify a bit to make it fitit’ll tell you about it by saying the patch applied withfuzz.You should be wary of such changes since even though patch probably got itright it doesn’t /always/ get it right, and the result will sometimes bewrong.

When patch encounters a change that it can’t fix up with fuzz it rejects itoutright and leaves a file with a.rej extension (a reject file). You canread this file to see exactly what change couldn’t be applied, so you cango fix it up by hand if you wish.

If you don’t have any third-party patches applied to your kernel source, butonly patches from kernel.org and you apply the patches in the correct order,and have made no modifications yourself to the source files, then you shouldnever see a fuzz or reject message from patch. If you do see such messagesanyway, then there’s a high risk that either your local source tree or thepatch file is corrupted in some way. In that case you should probably tryre-downloading the patch and if things are still not OK then you’d be advisedto start with a fresh tree downloaded in full from kernel.org.

Let’s look a bit more at some of the messages patch can produce.

If patch stops and presents aFiletopatch: prompt, then patch could notfind a file to be patched. Most likely you forgot to specify -p1 or you arein the wrong directory. Less often, you’ll find patches that need to beapplied with-p0 instead of-p1 (reading the patch file should reveal ifthis is the case -- if so, then this is an error by the person who createdthe patch but is not fatal).

If you getHunk#2succeededat1887withfuzz2(offset7lines). or amessage similar to that, then it means that patch had to adjust the locationof the change (in this example it needed to move 7 lines from where itexpected to make the change to make it fit).

The resulting file may or may not be OK, depending on the reason the filewas different than expected.

This often happens if you try to apply a patch that was generated against adifferent kernel version than the one you are trying to patch.

If you get a message likeHunk#3FAILEDat2387., then it means that thepatch could not be applied correctly and the patch program was unable tofuzz its way through. This will generate a.rej file with the change thatcaused the patch to fail and also a.orig file showing you the originalcontent that couldn’t be changed.

If you getReversed(orpreviouslyapplied)patchdetected! Assume-R?[n]then patch detected that the change contained in the patch seems to havealready been made.

If you actually did apply this patch previously and you just re-applied itin error, then just say [n]o and abort this patch. If you applied this patchpreviously and actually intended to revert it, but forgot to specify -R,then you can say [y]es here to make patch revert it for you.

This can also happen if the creator of the patch reversed the source anddestination directories when creating the patch, and in that case revertingthe patch will in fact apply it.

A message similar topatch:****unexpectedendoffileinpatch orpatchunexpectedlyendsinmiddleofline means that patch could make nosense of the file you fed to it. Either your download is broken, you tried tofeed patch a compressed patch file without uncompressing it first, or the patchfile that you are using has been mangled by a mail client or mail transferagent along the way somewhere, e.g., by splitting a long line into two lines.Often these warnings can easily be fixed by joining (concatenating) thetwo lines that had been split.

As I already mentioned above, these errors should never happen if you applya patch from kernel.org to the correct version of an unmodified source tree.So if you get these errors with kernel.org patches then you should probablyassume that either your patch file or your tree is broken and I’d advise youto start over with a fresh download of a full kernel tree and the patch youwish to apply.

Are there any alternatives topatch?¶

Yes there are alternatives.

You can use theinterdiff program (http://cyberelk.net/tim/patchutils/) togenerate a patch representing the differences between two patches and thenapply the result.

This will let you move from something like 5.7.2 to 5.7.3 in a singlestep. The -z flag to interdiff will even let you feed it patches in gzip orbzip2 compressed form directly without the use of zcat or bzcat or manualdecompression.

Here’s how you’d go from 5.7.2 to 5.7.3 in a single step:

interdiff -z ../patch-5.7.2.gz ../patch-5.7.3.gz | patch -p1

Although interdiff may save you a step or two you are generally advised todo the additional steps since interdiff can get things wrong in some cases.

Another alternative isketchup, which is a python script for automaticdownloading and applying of patches (https://www.selenic.com/ketchup/).

Other nice tools are diffstat, which shows a summary of changes made by apatch; lsdiff, which displays a short listing of affected files in a patchfile, along with (optionally) the line numbers of the start of each patch;and grepdiff, which displays a list of the files modified by a patch wherethe patch contains a given regular expression.

Where can I download the patches?¶

The patches are available athttps://kernel.org/Most recent patches are linked from the front page, but they also havespecific homes.

The 5.x.y (-stable) and 5.x patches live at

https://www.kernel.org/pub/linux/kernel/v5.x/

The 5.x.y incremental patches live at

https://www.kernel.org/pub/linux/kernel/v5.x/incr/

The -rc patches are not stored on the webserver but are generated ondemand from git tags such as

https://git.kernel.org/torvalds/p/v5.1-rc1/v5.0

The stable -rc patches live at

https://www.kernel.org/pub/linux/kernel/v5.x/stable-review/

The 5.x kernels¶

These are the base stable releases released by Linus. The highest numberedrelease is the most recent.

If regressions or other serious flaws are found, then a -stable fix patchwill be released (see below) on top of this base. Once a new 5.x basekernel is released, a patch is made available that is a delta between theprevious 5.x kernel and the new one.

To apply a patch moving from 5.6 to 5.7, you’d do the following (notethat such patches doNOT apply on top of 5.x.y kernels but on top of thebase 5.x kernel -- if you need to move from 5.x.y to 5.x+1 you need tofirst revert the 5.x.y patch).

Here are some examples:

# moving from 5.6 to 5.7$ cd ~/linux-5.6                # change to kernel source dir$ patch -p1 < ../patch-5.7      # apply the 5.7 patch$ cd ..$ mv linux-5.6 linux-5.7        # rename source dir# moving from 5.6.1 to 5.7$ cd ~/linux-5.6.1              # change to kernel source dir$ patch -p1 -R < ../patch-5.6.1 # revert the 5.6.1 patch                                # source dir is now 5.6$ patch -p1 < ../patch-5.7      # apply new 5.7 patch$ cd ..$ mv linux-5.6.1 linux-5.7      # rename source dir

The 5.x.y kernels¶

Kernels with 3-digit versions are -stable kernels. They contain small(ish)critical fixes for security problems or significant regressions discoveredin a given 5.x kernel.

This is the recommended branch for users who want the most recent stablekernel and are not interested in helping test development/experimentalversions.

If no 5.x.y kernel is available, then the highest numbered 5.x kernel isthe current stable kernel.

The -stable team provides normal as well as incremental patches. Below ishow to apply these patches.

$ cd ~/linux-5.7.2              # change to the kernel source dir$ patch -p1 -R < ../patch-5.7.2 # revert the 5.7.2 patch$ patch -p1 < ../patch-5.7.3    # apply the new 5.7.3 patch$ cd ..$ mv linux-5.7.2 linux-5.7.3    # rename the kernel source dir

$ cd ~/linux-5.7.2              # change to the kernel source dir$ patch -p1 < ../patch-5.7.2-3  # apply the new 5.7.3 patch$ cd ..$ mv linux-5.7.2 linux-5.7.3    # rename the kernel source dir

The -rc kernels¶

These are release-candidate kernels. These are development kernels releasedby Linus whenever he deems the current git (the kernel’s source managementtool) tree to be in a reasonably sane state adequate for testing.

These kernels are not stable and you should expect occasional breakage ifyou intend to run them. This is however the most stable of the maindevelopment branches and is also what will eventually turn into the nextstable kernel, so it is important that it be tested by as many people aspossible.

This is a good branch to run for people who want to help out testingdevelopment kernels but do not want to run some of the really experimentalstuff (such people should see the sections about -next and -mm kernels below).

The -rc patches are not incremental, they apply to a base 5.x kernel, justlike the 5.x.y patches described above. The kernel version before the -rcNsuffix denotes the version of the kernel that this -rc kernel will eventuallyturn into.

So, 5.8-rc5 means that this is the fifth release candidate for the 5.8kernel and the patch should be applied on top of the 5.7 kernel source.

Here are 3 examples of how to apply these patches:

# first an example of moving from 5.7 to 5.8-rc3$ cd ~/linux-5.7                        # change to the 5.7 source dir$ patch -p1 < ../patch-5.8-rc3          # apply the 5.8-rc3 patch$ cd ..$ mv linux-5.7 linux-5.8-rc3            # rename the source dir# now let's move from 5.8-rc3 to 5.8-rc5$ cd ~/linux-5.8-rc3                    # change to the 5.8-rc3 dir$ patch -p1 -R < ../patch-5.8-rc3       # revert the 5.8-rc3 patch$ patch -p1 < ../patch-5.8-rc5          # apply the new 5.8-rc5 patch$ cd ..$ mv linux-5.8-rc3 linux-5.8-rc5        # rename the source dir# finally let's try and move from 5.7.3 to 5.8-rc5$ cd ~/linux-5.7.3                      # change to the kernel source dir$ patch -p1 -R < ../patch-5.7.3         # revert the 5.7.3 patch$ patch -p1 < ../patch-5.8-rc5          # apply new 5.8-rc5 patch$ cd ..$ mv linux-5.7.3 linux-5.8-rc5          # rename the kernel source dir

The -mm patches and the linux-next tree¶

The -mm patches are experimental patches released by Andrew Morton.

In the past, -mm tree were used to also test subsystem patches, but thisfunction is now done via thelinux-next (https://www.kernel.org/doc/man-pages/linux-next.html)tree. The Subsystem maintainers push their patches first to linux-next,and, during the merge window, sends them directly to Linus.

The -mm patches serve as a sort of proving ground for new features and otherexperimental patches that aren’t merged via a subsystem tree.Once such patches has proved its worth in -mm for a while Andrew pushesit on to Linus for inclusion in mainline.

The linux-next tree is daily updated, and includes the -mm patches.Both are in constant flux and contains many experimental features, alot of debugging patches not appropriate for mainline etc., and is the mostexperimental of the branches described in this document.

These patches are not appropriate for use on systems that are supposed to bestable and they are more risky to run than any of the other branches (makesure you have up-to-date backups -- that goes for any experimental kernel buteven more so for -mm patches or using a Kernel from the linux-next tree).

Testing of -mm patches and linux-next is greatly appreciated since the wholepoint of those are to weed out regressions, crashes, data corruption bugs,build breakage (and any other bug in general) before changes are merged intothe more stable mainline Linus tree.

But testers of -mm and linux-next should be aware that breakages aremore common than in any other tree.

This concludes this list of explanations of the various kernel trees.I hope you are now clear on how to apply the various patches and help testingthe kernel.

Thank you’s to Randy Dunlap, Rolf Eike Beer, Linus Torvalds, Bodo Eggert,Johannes Stezenbach, Grant Coady, Pavel Machek and others that I may haveforgotten for their reviews and contributions to this document.