Differences between revisions 3 and 28 (spanning 25 versions)
Revision 3 as of 2009-01-15 03:06:06
Size: 2410
Editor: ?timrichardson
Comment:
Revision 28 as of 2020-07-22 06:55:11
Size: 6838
Comment: Clarify the case of test/data/absolutepath.zip
Deletions are marked like this. Additions are marked like this.
Line 2: Line 2:
||<tablewidth="100%"style="border: 0px hidden ;">~-[:DebianWiki/EditorGuide#translation:Translation(s)]: none-~ ||<style="border: 0px hidden ; text-align: right;"> (!) ["/Discussion"] || ||<tablewidth="100%"style="border: 0px hidden ;">~-[[DebianWiki/EditorGuide#translation|Translation(s)]]: English - [[it/UsingQuilt|Italiano]]-~||<style="border: 0px hidden ; text-align: right;"> (!) [[/Discussion]] ||
Line 4: Line 4:
 . 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
## If your page gets really long, uncomment this Table of Contents
## [[TableOfContents(2)]]

<<TableOfContents()>>

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: [[http://www.debian.org/doc/devel-manuals#maint-guide|Debian New Maintainers' Guide]].
 * A comprehensive yet succinct tutorial on quilt, [[http://raphaelhertzog.com/2012/08/08/how-to-use-quilt-to-manage-patches-in-debian-packages|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: [[https://perl-team.pages.debian.net/howto/quilt.html|Quilt for Debian Maintainers]].
 * There is also a [[http://www.shakthimaan.com/downloads/glv/quilt-tutorial/quilt-doc.pdf|Quilt Tutorial]] (PDF), though dated (2006)
 * If using a git packaging workflow, consider using [[http://honk.sigxcpu.org/projects/git-buildpackage/manual-html/man.gbp.pq.html|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

{{{#!wiki yellow
 $ quilt import some_package.diff.gz
}}}
Line 10: Line 33:
=== 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"
}}}
Line 11: Line 47:
consider adding these lines to .bashrc. Otherwise, run them in your shell or terminal before using quilt Alternatively, you can set environment variables yourself.
Line 13: Line 49:
{{{export QUILT_PATCHES=debian/patches}}} 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.
Line 15: Line 51:
{{{export QUILT_REFRESH_ARGS="-p ab --no-timestamps --no-index"}}} {{{#!wiki yellow
export QUILT_PATCHES=debian/patches <<BR>>
export QUILT_REFRESH_ARGS="-p ab --no-timestamps --no-index"
}}}
Line 17: Line 56:
== Basic quilt tasks: Making a new patch ==
The source code unpacked by apt-get source does not have patches applied.
=== 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.
Line 22: Line 80:
{{{quilt push -a}}} to "push" all existing patches onto the source tree (when you build a package, this is done by the build scripts) {{{#!wiki yellow
quilt push -a
}}} to "push" all existing patches onto the source tree (when you build a package, this is done by the build scripts)
Line 26: Line 86:
{{{quilt new myPatch.diff # this is the patch name}}} {{{#!wiki yellow
quilt new myPatch.diff # this is the patch name
}}}
Line 28: Line 90:
{{{quilt add README # you have to do that for all files you modify before you change them; one quilt patch can change multiple files}}} '''adding a file'''

{{{#!wiki yellow
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
Line 32: Line 102:
Now, make you changes to the files added to the patch: edit it, or replace it with an already modified file stored in a different directory. 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.
Line 36: Line 106:
{{{quilt refresh #you can do this as often as you like}}} {{{#!wiki yellow
quilt refresh #you can do this as often as you like
}}}

'''Add description to the header'''

{{{#!wiki yellow
quilt header -e #edits the header in $EDITOR
}}}
Line 40: Line 118:
{{{ quilt pop -a #this un-applies all patches so that the source returns to the downloaded condition }}} {{{#!wiki yellow
quilt pop -a
}}}
T
his un-applies all patches so that the source returns to the downloaded condition
Line 42: Line 123:
== Basic quilt tasks: Editing an existing patch == === Editing an existing patch ===
Line 50: Line 131:
{{{ quilt push myPatch.diff}}} {{{#!wiki yellow
quilt push myPatch.diff
}}}
Line 52: Line 135:
Now edit it, and when ready Now edit it, and when ready save it
Line 54: Line 137:
{{{ quilt refresh myPatch.diff   #note: command line completion may save you some typing }}} {{{#!wiki yellow
quilt refresh myPatch.diff
}}}
C
ommand line completion may save you some typing
Line 56: Line 142:
{{{ quilt pop -a}}} === 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 ===

{{{#!wiki yellow
quilt header -e
}}}

Now that we've saved our changes, remove all patches and return the source to its original state

{{{#!wiki yellow
quilt pop -a
}}}
Line 59: Line 196:
 . CategoryPortal | CategorySoftware
CategoryPackaging

Translation(s): English - Italiano

(!) ?/Discussion


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

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 #edits the header in $EDITOR

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


CategoryPackaging