diff options
Diffstat (limited to 'doc')
| -rw-r--r-- | doc/README.in | 115 | ||||
| -rw-r--r-- | doc/consider-for-docs-1.mail | 109 | ||||
| -rw-r--r-- | doc/consider-for-docs-2.mail | 77 | ||||
| -rw-r--r-- | doc/consider-for-docs-3.mail | 56 | ||||
| -rw-r--r-- | doc/docco.txt | 717 |
5 files changed, 1074 insertions, 0 deletions
diff --git a/doc/README.in b/doc/README.in new file mode 100644 index 0000000..83f252c --- /dev/null +++ b/doc/README.in @@ -0,0 +1,115 @@ +The scripts in this package simplify working with a series of patches. +The usual tasks like applying, refreshing and reversing are supported. + +docco.txt contains Adrew Morton's description of his suite of patch +scripts. These scripts are based on Andrew's scripts, but include many +changes. Please keep this in mind when reading Andrew's documentation. + + +Concepts +======== + +(Please see docco.txt.) + +The scripts maintain a stack of patches, on top of which additional +patches can be applied, and from with patches can be removed. The list of +patches is kept in a file (searched for in this order in +.pc/series, series, patches/series). + +The scripts keep meta information in the .pc/ directory. The .pc/ +directory contains: + + .pc/applied-patches + The list of currently applied patches. + + .pc/patch/.pc (for each applied patch) + A list of files modified by the patch. + + .pc/patch/ (for each applied patch) + Copies of the files that the patch modifies, + before modifying. The original versions of + the files are needed for refreshing patches, + and for ensuring that removing a patch does + recreate the original file contents. + + +Operation +========= + +Patches to be applied must be listed in the series file. + +Patches are applied with pushpatch, and are removed with poppatch. + +Refpatch refreshes a patch. + +New patches can be added at the current position in the patch sequence +with newpatch. + +Additional files to be modified can be added to a patch with patchadd. + + +Installation +============ + +To start using the scripts the working directory must contain: + + patches/ + Patches to work with. + + series (or patches/series) + List of patches in order of applying. + +The scripts will create the .pc/ directory that contains the meta +information needed for managing the patches automatically. + + +Series file +=========== + +The patches that are relevant for a project must be listed in the file +series, which is searched for in .pc/, ./ and patches/ in this order. +The patches will be applied in the order given. The series file has +the following format: + + # Comment + subdir/patch-file-name.patch [-pN] + +The location of patches is specified relative to the patches/ directory. +Optionally a strip level (-p0, -p1, etc.) can be specified. When +refreshing a patch, only levels 0 and 1 are supported. + + +Command reference +================= +@REFERENCE@ + +guards [--prefix=dir] [--path=dir1:dir2:...] [--default=0|1] + [--check] [--config=file] symbol ... + + Convert a series file with conditional statements into a series + file as expected; see the guards(1) manual page. + + +Helper files/scripts +==================== + +patchfns + A collection of functions. + +apatch + Add a patch. Used by pushpatch. + +rpatch + Remove a patch. Used by poppatch. + +parse-patch {-s|-u} section file [< replacement] + Select a %section from a patch (-s) or replace a + %section with the text from standard input (-u). + +touched-by-patch filename + Print a list of files modified by a patch file. + +backup-files + A simple utility that creates / restores / removes + backup files; this works around a patch bug (see BUGS). + diff --git a/doc/consider-for-docs-1.mail b/doc/consider-for-docs-1.mail new file mode 100644 index 0000000..ff45891 --- /dev/null +++ b/doc/consider-for-docs-1.mail @@ -0,0 +1,109 @@ +From: Andreas Gruenbacher <agruen@suse.de> +Organization: SuSE Linux AG +Subject: Patch Management Scripts +Date: Sat, 18 Jan 2003 18:40:32 +0100 + +Hello, + +this is to announce that the patch-scripts package is available at +http://www.suse.de/~agruen/patch-scripts/. The current version is 0.11. + +These scripts were based on Andrew Morton's patch scripts +(http://www.zip.com.au/~akpm/linux/patches/), but have been very +heavily modified since then. + +I am sure that there still a couple of bugs left, but these should +really be ironed out before long. + + +The scripts support: + +* Managing a stack of patches, applying and + removing patches from the stack, adding new patches, and + modifying them under a minimal kind of version control. + +* They should be reasonably robust (hopefully!). + +* Works for ordinary packages with only a few patches, and + also for the kernel with several hundered patches. + +* The refresh script is careful not to drop any documentation + preceding the actual patch in the patch files. + +* Simple to set up to get into "working mode" quickly. + +* Any applied patch can be refreshed. This is trivial for the + topmost patch. If a file is modified by multiple patches, + all changes to the file affect only the topmost patch that + changed that file; patches further below will not include + any such changes when being rediffed. + +* Several queries are supported, such as: + - topmost, preceding, following patch(es), + - files a patch creates or modifies + - patches that modify a given file + - changes a patch includes + - changes to a patch in the working directory + + +For those of you who are interested, here is a how to get started, after +grabbing and installing the patch-scripts package. + + +Patching an ordinary package: + + * The usual RPM contains a tarball and a set of + patches. Unpack the tarball and copy the + patches into the patches/ sub-directory in the + package. + + * Create a file named series in the patches/ directory. + The series file contains the list of patches for + the package. + + The patches are applied with -p1 by default; for -p0 + or other style patches the series file must have + -p0 or similar after the patch name (but on the same + line). + + * Run `pushpatch -a' to apply all the patches. (Note + that the first run is slightly slower because lists + of files modified by the patches are created.) + + * Proceed with the README file in the patch-scripts + package. + + +Patching the kernel: + + * The kernel lives in a CVS repository. Check out this + tree, say in a directory called $KCVS. + + * Unpack the kernel tarball, e.g., in $SRC. Create the + patches/ directory, and add soft links to the various + patches.* directories in the CVS into the patches + directory, e.g., + + $ cd $SRC/patches + $ ln -s $KCVS/patches.* . + + * Create a series file. This is done like that: + + $ (cd $K_SRC/scripts ; \ + guards $(arch-symbols)) \ + < ../series.conf \ + > $SRC/patches/series + + * Change to $SRC, and run `pushpatch -qa' to apply + the patches (-q gives much less output). + + * As above, check the README in the patch-scripts + package, and try out what the individual scripts do. + +Cheers, +Andreas. + +------------------------------------------------------------------ + Andreas Gruenbacher SuSE Linux AG + mailto:agruen@suse.de Deutschherrnstr. 15-19 + http://www.suse.de/ D-90429 Nuernberg, Germany diff --git a/doc/consider-for-docs-2.mail b/doc/consider-for-docs-2.mail new file mode 100644 index 0000000..bad5c27 --- /dev/null +++ b/doc/consider-for-docs-2.mail @@ -0,0 +1,77 @@ +From: Andreas Gruenbacher <agruen@suse.de> +Organization: SuSE Linux AG +To: quilt-dev@nongnu.org +Subject: My current quilt 0.21 :) +Date: Tue, 28 Jan 2003 22:05:15 +0100 + +Hi, + +I have copied my current version to http://www.suse.de/~agruen/quilt/. +Should we use this version to reload the CVS? I think we are nearing +the stable development phase, so now this seems to make some sense. + +There are surely many new bugs. Please help shake them out :) + +I also didn't merge several improvements. Would it be possible that +people contribute patches for the things they want included? I really +don't have so much time to work on features I don't need so much. + +Here's a list of changes (some probably forgotten): + + - There now is a quilt wrapper script. All the individual + commands are run from this script. This is a pain for frequently + used commands like push and pop. (I am using shell aliases + for some of them, which works well.) + + - The scripts have been split into many separate commands that + are intended to do only a few things each. + + $ quilt + Usage: quilt command [-h] ... + Commands are: + add files patches refresh setup + applied import pop remove top + delete new previous rest + diff next push series + + - .gz and .bz2 compressed patches are now suported. + + - Quilt setup takes a series file, unpacks archive(s), and + copies patches in. + + - For those working with RPMs, quilt setup can process an RPM + spec file and produces the series file from that (by running the + %prep section). + + - Quilt diff can diff a specified patch, diff the changes + done relative to after a patch, and create combined diffs. + + - Quilt series shows which patches are applied, + which is the topmost, and which are unapplied: + + $ quilt series -v + + samba-2.2.4-smbadduser + + samba-2.2.3-smbsh + + samba-2.2.6-doc + + samba-2.2.6-pdbedit + + samba-2.2.7a-removeldap + = samba-2.2.5-linkvfs + samba-2.2.7-nettime + samba-2.2.7a-acl-mapping-fixes + samba-2.2.7a-glibc + + - Quilt files shows which files are new/removed by a patch (none + are removed here): + + $ quilt files -v + fs/Config.in + fs/Makefile + + fs/posix_acl.c + + include/linux/posix_acl.h + + - Quilt import still sucks. Some ideas are found in the TODO. + + +So long, +Andreas. + diff --git a/doc/consider-for-docs-3.mail b/doc/consider-for-docs-3.mail new file mode 100644 index 0000000..4672ae2 --- /dev/null +++ b/doc/consider-for-docs-3.mail @@ -0,0 +1,56 @@ +From: Andreas Gruenbacher <agruen@suse.de> +Organization: SuSE Linux AG +To: Andrew Morton <akpm@digeo.com> +Subject: Patch scripts 0.9 improvements +Date: Tue, 7 Jan 2003 14:39:16 +0100 + +Hi Andrew, + +I still find your patch management scripts very useful. There are a fewg +small limitations that still keeps me from using them for the SuSEg +kernel at the moment. Particularly I need a way to have sub-directoriesg +in patches/ etc. + +Please find some improvements and ideas in the attached patch. + +Also I think it would be a good idea to keep all (non-temporary)g +information pertaining to a patch in a single file, rather thang +splitting into .patch, .txt, .pc files. I have a format like theg +following in mind. A simple parser for that proposed format is alsog +attached. + + Summary: Test patch + Author: Andreas Gruenbacher <agruen@suse.de> + URL: http://www.suse.de/ + + %description + DESCRIPTION + + %files + FILE1 + FILE2 + FILE3 + + %patch + PATCH + +I think that it doesn't make much sense to keep the .pc files (%filesg +section) as part of the patch set; they can easily be regenerated fromg +the .patch files. They are useful while working on a set of patchesg +though. What do you think of always generating them on the fly, insteadg +of using import_patch? Then the patches and series files could beg +checked out from CVS, and patching could start immediately; no cruftg +would assemble in the .pc files. + +Another idea: Maybe all the *~* files could live in their own directoryg +tree, e.g., under pc/? Then the file names would become more simple,g +e.g., from file.x~patch to ps/patch/file.x and file.x~dir_patch tog +dir/patch/file.x, with a smaller chance of clashes. What do you think +of that? + +Cheers, +Andreas. + + +[ Attachments removed ] + diff --git a/doc/docco.txt b/doc/docco.txt new file mode 100644 index 0000000..1860f13 --- /dev/null +++ b/doc/docco.txt @@ -0,0 +1,717 @@ +Patch management scripts +Andrew Morton <akpm@digeo.com> +18 October 2002 + +This is a description of a bunch of shell scripts which I use for +managing kernel patches. They are quite powerful. They can be used on +projects other than the linux kernel. They are easy to use, and fast. + +You end up doing a ton of recompiling with these scripts, because +you're pushing and popping all the time. ccache takes away the pain of +all that. http://ccache.samba.org/ - be sure to put the cache +directory on the same fs as where you're working so that ccache can use +hardlinks. + +The key philosophical concept is that your primary output is patches. +Not ".c" files, not ".h" files. But patches. So patches are the +first-class object here. + +Installation +============ + +You place all the scripts somewhere in your path, or in +/usr/lib/patch-scripts. + +Terminology +=========== + +The patch scripts require three special directories called "pc", +"patches" and "txt". + +If the environment variable PATCHSCRIPTS is set, it is taken to to be +the directory in which those three directories reside. Typically, it +would be a relative pathname. So + + setenv PATCHSCRIPTS ./i-put-them-here + +would tell the patch scripts to look in ./i-put-them-here/pc, etc. + +If PATCHSCRIPTS is not set, and the directory ./patch-scripts is +present then the patch scripts will us ./patch-scripts/pc/, +./patch-scripts/patches/ and ./patch-scripts/txt/. + +Otherwise, the patch scripts use ./pc, ./patches and ./txt. + +In this document, the symbol $P is used to describe the directory which +holds the pc/, patches/ and txt/ directories, as determined by the +above search. + +It is expected that $P will always expand to a relative path. + +Concepts +======== + +All work occurs with a single directory tree. All commands are invoked +within the root of that tree. The scripts manage a "stack" of patches. + +Each patch is a changeset against the base tree plus the preceding patches. + +All patches are listed, in order, in the file ./series. You manage the +series file. Lines in the series file which start with `#' are ignored. + +Any currently-applied patches are described in the file +./applied-patches. The patch scripts manage this file. + +Each patch affects a number of files in the tree. These files are +listed in a "patch control" file. These .pc files live in the +directory $P/pc/ + +Patches are placed in the directory $P/patches/ + +Documentation for the patches is placed in $P/txt/ + +So for a particular patch "my-first-patch" the following will exist: + +- An entry "my-first-patch.patch" in ./series + +- An entry "my-first-patch" in ./applied-patches (if it's currently applied) + +- A file $P/pc/my-first-patch.pc which contains the names of the + files which my-first-patch modifies, adds or removes + +- A file $P/txt/my-first-patch.txt which contains the patch's + changelog. + +- A file $P/patches/my-first-patch.patch, which is the output of the + patch scripts. + +Operation +========= + +When a patch "my-patch" is applied with apatch, or with pushpatch +(which calls apatch), all the affected files (from $P/pc/my-patch.pc) +are copied to files with ~my-patch appended. So if $P/pc/my-patch.pc +contained + + kernel/sched.c + fs/inode.c + +then apatch will copy those files into kernel/sched.c~my-patch and +fs/inode.c~my-patch. It will then apply the patch to kernel/sched.c +and fs/inode.c + +When a diff is regenerated by refpatch (which calls mpatch), the diff +is made between kernel/sched.c and kernel/sched.c~my-patch. How do the +scripts know to use "~my-patch"? Because my-patch is the current +topmost patch. It's the last line in ./applied-patches. + +In this way, the whole thing is stackable. If you have four patches +applied, say "patch-1", "patch-2", "patch-3" and "patch-4", and if +patch-2 and patch-4 both touch kernel/sched.c then you will have: + + kernel/sched.c~patch-2 Original copy, before patch-2 + kernel/sched.c~patch-4 Copy before patch-4. Contains changes + from patch-2 + kernel/sched.c Current working copy. Contains changes + from patch-4. + +This means that your diff headers contain "~patch-name" in them, which +is convenient documentation. + +Walkthrough +=========== + +Let's start. + +Go into /usr/src/linux (or wherever) + + mkdir pc patches txt + +Now let's generate a patch + + fpatch my-patch kernel/sched.c + +OK, we've copied kernel/sched.c to kernel/sched.c~my-patch. We've +appended "my-patch" to ./applied-patches and we've put "kernel/sched.c" +into the patch control file, pc/my-patch.pc. + + Now edit kernel/sched.c a bit. + +Now we're ready to document the patch + + Now write txt/my-patch.txt + +Now generate the patch + + refpatch + +This will generate patches/my-patch.patch. Take a look. + +Now remove the patch + + poppatch + +applied-patches is now empty, and the patch is removed. + +Now let's add a file to my-patch and then generate my-second-patch: + + Add "my-patch.patch" to ./series (no blank lines in that file please) + + pushpatch + +OK, the patch is applied again. Let's add another file + + fpatch kernel/printk.c + +Note that here we gave fpatch a single argument. So rather than +opening a new patch, it adds kernel/printk.c to the existing topmost +patch. That's my-patch. + + Edit kernel/printk.c + +Refresh my-patch (you end up running refpatch a lot) + + refpatch + +Now start a second patch: + + fpatch my-second-patch kernel/sched.c + +Now take a look at applied-patches. Also do an `ls kernel/sched*'. + + Edit kernel/sched.c, to make some changes for my-second-patch + +Generate my-second-patch: + + refpatch + +Take a look in patches/my-second-patch.patch + +Don't forget to add "my-second-patch.patch" to the series file. + +And remove both patches: + + poppatch + poppatch + + +That's pretty much it, really. + + +Command reference +================= + +Generally, where any of these commands take a "patch-name", that can be +of the form txt/patch-name.txt, patch-name.pc, just patch-name or +whatever. The scripts will strip off a leading "txt/", "patches/" or +"pc/" and any trailing extension. This is so you can do + + apatch patches/a<tab> + +to conveniently use shell tabbing to select patch names. + + + +added-by-patch + + Some internal thing. + +apatch [-f] patch-name + + This is the low-level function which adds patches. It does the + copying into ~-files and updates the applied-patches file. It + applies the actual patch. + + apatch will do a patch --dry-run first and will refuse to apply the + patch if the dryrun fails. + + So when you are getting rejects you do this: + + pushpatch # This fails, due to rejects. Drat. + apatch -f patch-name # Force the patch + (or) pushpatch -f # Force the patch + + OK, you've now applied patch-name, but you have rejects. Go fix + those up and do + + refpatch + + And you're ready to move on. + +combine-series output-file + + It incrementally combinediffs all the patches in series to make a + complete patch for the series. Requires combinediff frmo patchutils. + + See http://cyberelk.net/tim/patchutils/ (Don't download the + "experimental" patchutils - it seems to only have half of the + commands in it. Go for "stable") + +cvs-take-patch + + I forget. + +export_patch + + export the patches listed in ./series to a set of files which + are named in such a way that the sort order is the same as the + order of the series file. + + Usage: export_patch directory [prefix] + + Example: + + Suppose ./series contains + + mango.patch + orange.patch + banana.patch + apple.patch + pear.patch + + export_patch ../mypatches fruit + + The patches would be copied to + + ../mypatches/p00001_fruit_mango.patch + ../mypatches/p00002_fruit_orange.patch + ../mypatches/p00003_fruit_banana.patch + ../mypatches/p00003_fruit_banana.patch + ../mypatches/p00003_fruit_banana.patch + + Named in this way, someone may easily apply them: + + cat mypatches/p*fruit* | patch -p1 + + If prefix is omitted, the patchnames will be transformed + such that "original.patch" becomes "pXXXXX_original.patch". + +fpatch [patch-name] foo.c + + If patch-name is given, fpatch will start a new patch which + modifies (or adds, or removes) the single file foo.c. It updates + ./applied-patches and creates pc/patch-name.pc. fpatch will copy + foo.c to foo.c~patch-name in preparation for edits of foo.c. + + If patch-name is not given then fpatch will add foo.c to the + current topmost patch. It will add "foo.c" to $P/pc/$(toppatch).pc. + It will copy foo.c to foo.c~$(toppatch). + +import_patch + + Imports a set of patch files, creating $P/pc, $P/txt, $P/patches and + ./series as necessary. It also creates $P/txt/*.txt by stripping + off the top of the patches (and removes any diffstat output it finds, + so that it can eat refpatch output and export_patch output.) The + imported patch names are appended to the series file. + + In creating the $P/txt/*.txt files, mail headers are stripped with + formail, preserving the "From:" and "Subject:" lines. "DESC" and + "EDESC" markers are added if they are not already present, using the + "From:" and "Subject:" lines for the DESC portion, if they are present. + (See "patchdesc" command, below, for more on these markers.) + + Also, it can rename the patch file as it is imported by stripping out + a pattern. This is useful if, as often is the case, you have patch + sets with filenames designed to help sort the patches into the correct + order, such as "p001_xxx_funky_stuff.patch" you can have it automatically + renamed to funky_stuff.patch on import, and let the series file manage + the ordering. + + Import_patch will uncompress patches (*.Z, *.bz2, *.gz) as necessary. + + Usage: + + import_patch [-p pattern] patchfile ... + + Example: + + % ls ../fruit/p*patch + ../fruit/p00001_northern_apple.patch + ../fruit/p00001_tropical_mango.patch + ../fruit/p00002_northern_pear.patch + ../fruit/p00002_tropical_orange.patch + ../fruit/p00003_tropical_banana.patch + % import_patch -p 'p[0-9]*_tropical_' ../fruit/p*tropical* + Recreated pc/mango.pc + Recreated pc/orange.pc + Recreated pc/banana.pc + % import_patch -p 'p[0-9]*_northern_' ../fruit/p*northern* + Recreated pc/apple.pc + Recreated pc/pear.pc + + Then you can "pushpatch; refpatch" 5 times. + +inpatch + + List the names of ths files which are affected by the current + topmost patch. + + This is basically + + cat pc/$(toppatch).pc + +join-patch patchname + + "joins" the named patch to the current topmost patch. + + Use this when you want to merge two patches into one. All the + files which `patchname' affects are added to pc/$(toppatch).pc (if + they are not already there) and patch `patchname' is applied. The + top patch remains unchanged. You'll need to run refpatch afterwards. + +mpatch + + A low-level thing to generate patches + +new-kernel + + Some thing I use for importing a new kernel from kernel.org + +p0-2-p1 + + Internal thing to convert patch -p0 form into patch -p1 + +patchdesc + + Generates a single-line description of a patch. + + The txt/my-patch.txt files have the following format: + + <start of file> + DESC + some short description + EDESC + + The long description + <end of file> + + I use + + patchdesc $(cat series) + + to generate short-form summaries of the patch series. + +patchfns + + Internal utilities + +pcpatch + + Standalone tool to generate a .pc file from a patch. + + Say someone sends you "his-patch.diff". What you do is: + + cp ~/his-patch.diff patches/his-patch.patch + pcpatch his-patch + + This generates $P/pc/his-patch.pc and you're all set. Add + "his-patch.patch" to ./series in the right place and start pushing. + +p_diff + + I forget + +poppatch + + Remove one or more patches from the current stack. This command + does *not* use the series file. It works purely against + applied-patches. + + Usage: + + poppatch + Remove the topmost patch + poppatch 10 + Remove ten patches + poppatch some-patch-name[.patch] + Remove patches until "some-patch-name" is top patch + +pstatus + + Shows status of patches + + Usage: + pstatus [patchfile ...] + + One line per patch is output showing: + 1: Patch number in the series file + 2: Whether the patch is currently applied + 3: Name of patch + 4: Status of the patch (needs pcpatch, changelog, refpatch) + + If no patchfiles are specified, $P/patches/*.patch + are assumed. + + Caveats: + A patch set which contains separate patches to add a file + and modify that same file may give spurious "Needs refpatch" + status for the patch which adds the file or the topmost patch. + +ptkdiff + + Two modes: + + ptkdiff - + + Run tkdiff against all the file affected + by $(toppatch). The diff is only for the changes made + by the top patch! ie: it's between "filename" and + "filename~toppatch-name". + + ptkdiff filename + + Just run tkdiff against that file, + showing the changes which are due to toppatch. + +pushpatch [-f] + + Apply the next patch, from the series file. + + This consults ./applied-patches to find out the top patch, then + consults ./series to find the next patch. And pushes it. + + pushpatch + + Apply the next patch + + pushpatch 10 + + Apply the next ten patches + + pushpatch some-patch-name + + Keep pushing patches until "some-patch-name" is toppatch + + pushpatch -f + + Push the next patch, ignoring rejects. + +refpatch + + regnerates the topmost patch. Reads all the affected files + from pc/$(toppatch).pc and diffs them against their tilde-files. + + Also pastes into the patch your patch documentation and + generates a diffstat summary. + +removed-by-patch + + Some thing. + +rename-patch + + CVS rename for patches. + +rolled-up-patch + + Bit of a hack. Is designed to generate a rolled-up diff of all + currently-applied patches. But it requires a ../linux-2.x.y tree to + diff against. Needs to be redone. + +rpatch + + Internal command + +split-patch + + Some thing someone write to split patches up. I don't use it. + +tag-series + + Assuming you keep pc/*, patches/* and txt/* under CVS revision + control, tag-series allows you to tag a patchset's individual + components. I use + + tag-series s2_5_44-mm3 pc/2.5.44-mm3-series + + which will attach the cvs tag "s2_5_44-mm3" to every .pc, .patch + and .txt file which is mentioned in the series file + "pc/2.5.44-mm3-series". + + It will also tag pc/2.5.44-mm3-series, which is a bit redundant + given that I use a different series file for each patchset release.. + + +toppatch + + Print the name of the topmost patch. From ./applied-patches + +touched-by-patch patch-filename + + List the names of files which are affected by a diff. + +unitdiff.py + + Rasmus Andersen's script to convert a diff into minimum-context + form. This form has a better chance of applying if you're getting + nasty rejects. But patch can and will make mistakes when fed + small-context input. + + +Work Practices +============== + +I keep the kernel tree, the $P/pc/, $P/patches/ and $P/txt/ contents under +CVS control. This is important... + +I have several "series" files. I keep these in $P/pc/foo-series and use + + ln -s pc/foo-series series + +when I'm working on foo. + +If someone sends me a patch I'll do: + + cp ~/whatever patches/his-patch.patch + pcpatch his-patch + apatch his-patch + + If apatch fails then run `apatch -f his-patch' and fix the rejects. + + refpatch + + to clean up any fuzz. + + poppatch + cvs add pc/his-patch.pc patches/his-patch.patch + cvs commit pc patches + + Now edit ./series and place "his-patch.patch" in the appropriate place. + + +If you're working on a particular patch (say, "dud-patch") and you +balls something up, just run: + + refpatch # Generate the crap patch + poppatch # Remove it all + rm patches/dud-patch.patch + cvs up patches/dud-patch.patch + +and all is well. + + +Getting updates from Linus +========================== + +What I do is to grab the latest -bk diff from +http://www.kernel.org/pub/linux/kernel/people/dwmw2/bk-2.5/ +and do: + + gzip -d < cs<tab> > patches/linus.patch + pcpatch linus + apatch linus | grep diff + + Now fix up all the files which got deleted, + because there's something wrong with bitkeeper diffs: + + cvs up -ko <missing files from the above diff> + + apatch linus + $EDITOR linus/linus.txt + + Add the changeset number to txt/linus.txt + + refpatch + poppatch + + Now add "linus.patch" as the first entry in your ./series file and + start pushing your other patches on top of that. + +BUGS +==== + +Tons and tons. The scripts are fragile, the error handling is ungraceful and +if you do something silly you can end up in a pickle. + +Generally the scripts are very careful to not wreck your files or your +patches. But they can get the ./applied-patches and ~-files into an +awkward state. + +Usually you can sort it out by copying the ~-files back onto the originals +and removing the last line from ./applied-patches. Or do a "refpatch ; +poppatch ; rm patches/troublesome-patch.patch ; cvs up patches". + +If it's really bad, just blow away the entire tree and do a new CVS checkout. + + +Working on non-kernel projects +============================== + +Well it's the same thing. Say you've downloaded a copy of util-linux +and you want to make a change: + + cd /usr/src + tar xvfz ~/util-linux.tar.gz + cd util-linux + mkdir pc patches txt + fpatch my-patch sys-utils/rdev.c + fpatch sys-utils/ipcs.8 + <edit, edit> + refpatch + <ship patches/my-patch.patch> + +How to balls things up +====================== + +Well here's one way. Suppose you have 20 patches applied, and three of +them (say, "p1", "p6" and "p11") all modify "foo.c". + +Now you go and change foo.c. + +Well, to which patch does that change belong? You need to decide. +Let's say you decide "p6". + +If you run `refpatch' when "p11" is toppatch then you lose. The diff +went into p11. + +What you can do is: + +1: + poppatch p6 + <edit> + refpatch + pushpatch p11 + <test> + + (See why ccache is looking good?) + +or + +2: + <edit> + <test> + poppatch p6 <hope like hell that the other patches remove cleanly> + refpatch + + +Another good way of ballsing up is to cheat. Say "oh I just want to make +this one-line change". And "oh, and this one". + +Now you're getting in a mess. It's much, much better to just use the system: + + fpatch junk file1 + fpatch file2 + <edit> + <play> + refpatch + poppatch + rm pc/junk.pc patches/junk.patch + +Merging with -mm kernels +======================== + +Haven't tried this, but it should work: + +- Grab all the patches from broken-out/, place them in your $P/patches/ + +- Copy my series file into ./series (or $P/pc/akpm-series and symlink it) + +- pushpatch 99 + +And you're off and running. The nice thing about this is that you can +send me incremental diffs to diffs which I already have. + +Or whatever. I'm fairly handy with diffs nowadays. Rejects are +expected. I just prefer to have "one concept per diff". + |