Contents
Using quilt in Debian source packages.
- This page is aimed at people who want to make some changes to a Debian source package which is already using quilt.
- The intention is not to explain quilt, but to offer some Debian specific tips
General information
documentation
If you want to understand how quilt work, install the package and read /usr/share/doc/quilt/quilt.pdf.gz
There is an extensive guide on quilt and packaging: Debian New Maintainers' Guide.
A comprehensive yet succinct tutorial on quilt, How to use quilt to manage patches in Debian packages, published by Raphaël Hertzog (coauthor of the New Maintainers' Guide above)
A How-To from the Debian Perl Group: Quilt for Debian Maintainers.
There is also a Quilt Tutorial (PDF), though dated (2006)
If using a git packaging workflow, consider using gbp-pq(1) for quilt patch management.
Basic concepts
quilt works with some directories : it creates a .pc/ and a patches/ directory.
Those directories can be created when you do
- $ quilt import some_package.diff.gz
Using quilt with Debian source packages
Situation: you have downloaded a Debian source package which uses quilt and want to fix a bug and then submit a patch to the maintainers.
Using .quiltrc configuration file
Place a .quiltrc configuration file in your home directory with the following lines.
QUILT_PATCHES=debian/patches QUILT_NO_DIFF_INDEX=1 QUILT_NO_DIFF_TIMESTAMPS=1 QUILT_REFRESH_ARGS="-p ab" QUILT_DIFF_ARGS="--color=auto" # If you want some color when using `quilt diff`. QUILT_PATCH_OPTS="--reject-format=unified" QUILT_COLORS="diff_hdr=1;32:diff_add=1;34:diff_rem=1;31:diff_hunk=1;33:diff_ctx=35:diff_cctx=33"
Environment variables
Alternatively, you can set environment variables yourself.
Add these lines to your shell's init scripts (~/.bashrc), and restart your shell to apply the changes. Or, run them in your shell before using quilt.
export QUILT_PATCHES=debian/patches
export QUILT_REFRESH_ARGS="-p ab --no-timestamps --no-index"
Encapsulated
To apply quilt options only when inside a Debian source package, you can setup your ~/.quiltrc something like this:
d=. ; while [ ! -d $d/debian -a `readlink -e $d` != / ]; do d=$d/..; done
if [ -d $d/debian ] && [ -z $QUILT_PATCHES ]; then
# if in Debian packaging tree with unset $QUILT_PATCHES
QUILT_PATCHES="debian/patches"
if ! [ -d $d/debian/patches ]; then mkdir $d/debian/patches; fi
fi
Basic quilt tasks
Making a new patch
apt-get source decides whether to apply the patches based on the format of the package.
For some packages, you will have to apply the patches as specified here. For others, they will be automatically applied.
First step: apply existing patches to the source
quilt push -a
to "push" all existing patches onto the source tree (when you build a package, this is done by the build scripts)
Creating a new patch
quilt new myPatch.diff # this is the patch name
adding a file
quilt add README # Where 'README' is the name of the file you want to modify.
You have to do that for all files you modify before you change them.
One quilt patch can change multiple files
Now make changes to the source
Now, make your changes to the files added to the patch: edit it, or replace it with an already modified file stored in a different directory.
Updating a patch with changes made to its files
quilt refresh #you can do this as often as you like
Add description to the header
quilt header -e --dep3 #edits the header in $EDITOR starting with the DEP-3 header template
Finish your editing
quilt pop -a
This un-applies all patches so that the source returns to the downloaded condition
Editing an existing patch
quilt supports multiple patches, but you are only ever change one of them.
This is the patch last pushed.
To edit an existing patch, start by pushing it
quilt push myPatch.diff
Now edit it, and when ready save it
quilt refresh myPatch.diff
Command line completion may save you some typing
Refresh a patch that failed to apply
If the patch failed to apply (usually when updating to a new upstream release) when you quilt push like the example below,
$ quilt push Applying patch CVE-2018-1000544_part1.patch patching file lib/zip/entry.rb Hunk #1 FAILED at 147. 1 out of 1 hunk FAILED -- rejects in file lib/zip/entry.rb patching file test/data/absolutepath.zip patching file test/entry_test.rb Patch CVE-2018-1000544_part1.patch does not apply (enforce with -f)
$ quilt push -f Applying patch CVE-2018-1000544_part1.patch patching file lib/zip/entry.rb Hunk #1 FAILED at 147. 1 out of 1 hunk FAILED -- saving rejects to file lib/zip/entry.rb.rej patching file test/data/absolutepath.zip patching file test/entry_test.rb Applied patch CVE-2018-1000544_part1.patch (forced; needs refresh)
Now you should inspect the *.rej files (lib/zip/entry.rb.rej in this example) and adapt lib/zip/entry.rb to include the desired change.
If the change has been incorporated upstream, you can remove the change from your patch. For example:
$ quilt refresh Diff failed on file 'test/data/absolutepath.zip', aborting # In this case the change to absolutepath.zip has already been performed upstream. # So let's remove the file from the patch: $ quilt remove test/data/absolutepath.zip File test/data/absolutepath.zip removed from patch CVE-2018-1000544_part1.patch $ quilt refresh
Update the header comments of the patch on the top of the stack
quilt header -e
Now that we've saved our changes, remove all patches and return the source to its original state
quilt pop -a
Forwarding Patches to Upstream
Non Debian-specific patches, such as patches for bug fixes and feature enhancements, need to be forwarded upstream: How to forward patches to upstream