1757e8328SLionel Sambuc.\" $OpenBSD: patch.1,v 1.22 2008/06/06 20:44:00 jmc Exp $ 2757e8328SLionel Sambuc.\" $DragonFly: src/usr.bin/patch/patch.1,v 1.10 2008/08/18 19:15:55 joerg Exp $ 3*0a6a1f1dSLionel Sambuc.\" $NetBSD: patch.1,v 1.19 2015/08/02 12:19:12 wiz Exp $ 4757e8328SLionel Sambuc.\" Copyright 1986, Larry Wall 5757e8328SLionel Sambuc.\" 6757e8328SLionel Sambuc.\" Redistribution and use in source and binary forms, with or without 7757e8328SLionel Sambuc.\" modification, are permitted provided that the following condition 8757e8328SLionel Sambuc.\" is met: 9757e8328SLionel Sambuc.\" 1. Redistributions of source code must retain the above copyright 10757e8328SLionel Sambuc.\" notice, this condition and the following disclaimer. 11757e8328SLionel Sambuc.\" 12757e8328SLionel Sambuc.\" THIS SOFTWARE IS PROVIDED BY THE AUTHOR AND CONTRIBUTORS ``AS IS'' AND 13757e8328SLionel Sambuc.\" ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE 14757e8328SLionel Sambuc.\" IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE 15757e8328SLionel Sambuc.\" ARE DISCLAIMED. IN NO EVENT SHALL THE AUTHOR OR CONTRIBUTORS BE LIABLE 16757e8328SLionel Sambuc.\" FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR CONSEQUENTIAL 17757e8328SLionel Sambuc.\" DAMAGES (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS 18757e8328SLionel Sambuc.\" OR SERVICES; LOSS OF USE, DATA, OR PROFITS; OR BUSINESS INTERRUPTION) 19757e8328SLionel Sambuc.\" HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT 20757e8328SLionel Sambuc.\" LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY 21757e8328SLionel Sambuc.\" OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF 22757e8328SLionel Sambuc.\" SUCH DAMAGE. 23757e8328SLionel Sambuc.\" 24*0a6a1f1dSLionel Sambuc.Dd August 2, 2015 25757e8328SLionel Sambuc.Dt PATCH 1 26757e8328SLionel Sambuc.Os 27757e8328SLionel Sambuc.Sh NAME 28757e8328SLionel Sambuc.Nm patch 29757e8328SLionel Sambuc.Nd apply a diff file to an original 30757e8328SLionel Sambuc.Sh SYNOPSIS 31757e8328SLionel Sambuc.Nm 32757e8328SLionel Sambuc.Op Fl bCcEeflNnRstuv 33757e8328SLionel Sambuc.Op Fl B Ar backup-prefix 34757e8328SLionel Sambuc.Op Fl D Ar symbol 35757e8328SLionel Sambuc.Op Fl d Ar directory 36757e8328SLionel Sambuc.Op Fl F Ar max-fuzz 37757e8328SLionel Sambuc.Op Fl i Ar patchfile 38757e8328SLionel Sambuc.Op Fl o Ar out-file 39757e8328SLionel Sambuc.Op Fl p Ar strip-count 40757e8328SLionel Sambuc.Op Fl r Ar rej-name 41*0a6a1f1dSLionel Sambuc.Op Fl V Cm t | nil | never | none 42757e8328SLionel Sambuc.Op Fl x Ar number 43757e8328SLionel Sambuc.Op Fl z Ar backup-ext 44757e8328SLionel Sambuc.Op Fl Fl posix 45757e8328SLionel Sambuc.Op Ar origfile Op Ar patchfile 46757e8328SLionel Sambuc.Nm 47757e8328SLionel Sambuc.Pf \*(Lt Ar patchfile 48757e8328SLionel Sambuc.Sh DESCRIPTION 49757e8328SLionel Sambuc.Nm 50757e8328SLionel Sambucwill take a patch file containing any of the four forms of difference 51757e8328SLionel Sambuclisting produced by the 52757e8328SLionel Sambuc.Xr diff 1 53757e8328SLionel Sambucprogram and apply those differences to an original file, 54757e8328SLionel Sambucproducing a patched version. 55757e8328SLionel SambucIf 56757e8328SLionel Sambuc.Ar patchfile 57757e8328SLionel Sambucis omitted, or is a hyphen, the patch will be read from the standard input. 58757e8328SLionel Sambuc.Pp 59757e8328SLionel Sambuc.Nm 60757e8328SLionel Sambucwill attempt to determine the type of the diff listing, unless over-ruled by a 61757e8328SLionel Sambuc.Fl c , 62757e8328SLionel Sambuc.Fl e , 63757e8328SLionel Sambuc.Fl n , 64757e8328SLionel Sambucor 65757e8328SLionel Sambuc.Fl u 66757e8328SLionel Sambucoption. 67757e8328SLionel SambucContext diffs (old-style, new-style, and unified) and 68757e8328SLionel Sambucnormal diffs are applied directly by the 69757e8328SLionel Sambuc.Nm 70757e8328SLionel Sambucprogram itself, whereas ed diffs are simply fed to the 71757e8328SLionel Sambuc.Xr ed 1 72757e8328SLionel Sambuceditor via a pipe. 73757e8328SLionel Sambuc.Pp 74757e8328SLionel SambucIf the 75757e8328SLionel Sambuc.Ar patchfile 76757e8328SLionel Sambuccontains more than one patch, 77757e8328SLionel Sambuc.Nm 78757e8328SLionel Sambucwill try to apply each of them as if they came from separate patch files. 79757e8328SLionel SambucThis means, among other things, that it is assumed that the name of the file 80757e8328SLionel Sambucto patch must be determined for each diff listing, and that the garbage before 81757e8328SLionel Sambuceach diff listing will be examined for interesting things such as file names 82757e8328SLionel Sambucand revision level (see the section on 83757e8328SLionel Sambuc.Sx Filename Determination 84757e8328SLionel Sambucbelow). 85757e8328SLionel Sambuc.Pp 86757e8328SLionel SambucThe options are as follows: 87757e8328SLionel Sambuc.Bl -tag -width Ds 88757e8328SLionel Sambuc.It Fl B Ar backup-prefix , Fl Fl prefix Ar backup-prefix 89757e8328SLionel SambucCauses the next argument to be interpreted as a prefix to the backup file 90757e8328SLionel Sambucname. 91757e8328SLionel SambucIf this argument is specified, any argument to 92757e8328SLionel Sambuc.Fl z 93757e8328SLionel Sambucwill be ignored. 94757e8328SLionel Sambuc.It Fl b , Fl Fl backup 95757e8328SLionel SambucSave a backup copy of the file before it is modified. 96757e8328SLionel SambucBy default the original file is saved with a backup extension of 97757e8328SLionel Sambuc.Qq .orig 98757e8328SLionel Sambucunless the file already has a numbered backup, in which case a numbered 99757e8328SLionel Sambucbackup is made. 100757e8328SLionel SambucThis is equivalent to specifying 101757e8328SLionel Sambuc.Qo Fl V Cm existing Qc . 102757e8328SLionel SambucThis option is currently the default, unless 103757e8328SLionel Sambuc.Fl -posix 104757e8328SLionel Sambucis specified. 105757e8328SLionel Sambuc.It Fl C , Fl Fl check 106757e8328SLionel SambucChecks that the patch would apply cleanly, but does not modify anything. 107757e8328SLionel Sambuc.It Fl c , Fl Fl context 108757e8328SLionel SambucForces 109757e8328SLionel Sambuc.Nm 110757e8328SLionel Sambucto interpret the patch file as a context diff. 111757e8328SLionel Sambuc.It Fl D Ar symbol , Fl Fl ifdef Ar symbol 112757e8328SLionel SambucCauses 113757e8328SLionel Sambuc.Nm 114757e8328SLionel Sambucto use the 115757e8328SLionel Sambuc.Qq #ifdef...#endif 116757e8328SLionel Sambucconstruct to mark changes. 117757e8328SLionel SambucThe argument following will be used as the differentiating symbol. 118757e8328SLionel SambucNote that, unlike the C compiler, there must be a space between the 119757e8328SLionel Sambuc.Fl D 120757e8328SLionel Sambucand the argument. 121757e8328SLionel Sambuc.It Fl d Ar directory , Fl Fl directory Ar directory 122757e8328SLionel SambucCauses 123757e8328SLionel Sambuc.Nm 124757e8328SLionel Sambucto interpret the next argument as a directory, 125757e8328SLionel Sambucand change the working directory to it before doing anything else. 126757e8328SLionel Sambuc.It Fl E , Fl Fl remove-empty-files 127757e8328SLionel SambucCauses 128757e8328SLionel Sambuc.Nm 129757e8328SLionel Sambucto remove output files that are empty after the patches have been applied. 130757e8328SLionel SambucThis option is useful when applying patches that create or remove files. 131757e8328SLionel Sambuc.It Fl e , Fl Fl ed 132757e8328SLionel SambucForces 133757e8328SLionel Sambuc.Nm 134757e8328SLionel Sambucto interpret the patch file as an 135757e8328SLionel Sambuc.Xr ed 1 136757e8328SLionel Sambucscript. 137757e8328SLionel Sambuc.It Fl F Ar max-fuzz , Fl Fl fuzz Ar max-fuzz 138757e8328SLionel SambucSets the maximum fuzz factor. 139757e8328SLionel SambucThis option only applies to context diffs, and causes 140757e8328SLionel Sambuc.Nm 141757e8328SLionel Sambucto ignore up to that many lines in looking for places to install a hunk. 142757e8328SLionel SambucNote that a larger fuzz factor increases the odds of a faulty patch. 143757e8328SLionel SambucThe default fuzz factor is 2, and it may not be set to more than 144757e8328SLionel Sambucthe number of lines of context in the context diff, ordinarily 3. 145757e8328SLionel Sambuc.It Fl f , Fl Fl force 146757e8328SLionel SambucForces 147757e8328SLionel Sambuc.Nm 148757e8328SLionel Sambucto assume that the user knows exactly what he or she is doing, and to not 149757e8328SLionel Sambucask any questions. 150757e8328SLionel SambucIt assumes the following: 151757e8328SLionel Sambucskip patches for which a file to patch can't be found; 152757e8328SLionel Sambucpatch files even though they have the wrong version for the 153757e8328SLionel Sambuc.Qq Prereq: 154757e8328SLionel Sambucline in the patch; 155757e8328SLionel Sambucand assume that patches are not reversed even if they look like they are. 156757e8328SLionel SambucThis option does not suppress commentary; use 157757e8328SLionel Sambuc.Fl s 158757e8328SLionel Sambucfor that. 159757e8328SLionel Sambuc.It Fl i Ar patchfile , Fl Fl input Ar patchfile 160757e8328SLionel SambucCauses the next argument to be interpreted as the input file name 161757e8328SLionel Sambuc(i.e., a patchfile). 162757e8328SLionel SambucThis option may be specified multiple times. 163757e8328SLionel Sambuc.It Fl l , Fl Fl ignore-whitespace 164757e8328SLionel SambucCauses the pattern matching to be done loosely, in case the tabs and 165757e8328SLionel Sambucspaces have been munged in your input file. 166757e8328SLionel SambucAny sequence of whitespace in the pattern line will match any sequence 167757e8328SLionel Sambucin the input file. 168757e8328SLionel SambucNormal characters must still match exactly. 169757e8328SLionel SambucEach line of the context must still match a line in the input file. 170757e8328SLionel Sambuc.It Fl N , Fl Fl forward 171757e8328SLionel SambucCauses 172757e8328SLionel Sambuc.Nm 173757e8328SLionel Sambucto ignore patches that it thinks are reversed or already applied. 174757e8328SLionel SambucSee also 175757e8328SLionel Sambuc.Fl R . 176757e8328SLionel Sambuc.It Fl n , Fl Fl normal 177757e8328SLionel SambucForces 178757e8328SLionel Sambuc.Nm 179757e8328SLionel Sambucto interpret the patch file as a normal diff. 180757e8328SLionel Sambuc.It Fl o Ar out-file , Fl Fl output Ar out-file 181757e8328SLionel SambucCauses the next argument to be interpreted as the output file name. 182757e8328SLionel Sambuc.It Fl p Ar strip-count , Fl Fl strip Ar strip-count 183757e8328SLionel SambucSets the pathname strip count, 184757e8328SLionel Sambucwhich controls how pathnames found in the patch file are treated, 185757e8328SLionel Sambucin case you keep your files in a different directory than the person who sent 186757e8328SLionel Sambucout the patch. 187757e8328SLionel SambucThe strip count specifies how many slashes are to be stripped from 188757e8328SLionel Sambucthe front of the pathname. 189757e8328SLionel Sambuc(Any intervening directory names also go away.) 190757e8328SLionel SambucFor example, supposing the file name in the patch file was 191757e8328SLionel Sambuc.Pa /u/howard/src/blurfl/blurfl.c : 192757e8328SLionel Sambuc.Pp 193757e8328SLionel SambucSetting 194757e8328SLionel Sambuc.Fl p Ns Ar 0 195757e8328SLionel Sambucgives the entire pathname unmodified. 196757e8328SLionel Sambuc.Pp 197757e8328SLionel Sambuc.Fl p Ns Ar 1 198757e8328SLionel Sambucgives 199757e8328SLionel Sambuc.Pp 200757e8328SLionel Sambuc.D1 Pa u/howard/src/blurfl/blurfl.c 201757e8328SLionel Sambuc.Pp 202757e8328SLionel Sambucwithout the leading slash. 203757e8328SLionel Sambuc.Pp 204757e8328SLionel Sambuc.Fl p Ns Ar 4 205757e8328SLionel Sambucgives 206757e8328SLionel Sambuc.Pp 207757e8328SLionel Sambuc.D1 Pa blurfl/blurfl.c 208757e8328SLionel Sambuc.Pp 209757e8328SLionel SambucNot specifying 210757e8328SLionel Sambuc.Fl p 211757e8328SLionel Sambucat all just gives you 212757e8328SLionel Sambuc.Pa blurfl.c , 213757e8328SLionel Sambucunless all of the directories in the leading path 214757e8328SLionel Sambuc.Pq Pa u/howard/src/blurfl 215757e8328SLionel Sambucexist and that path is relative, 216757e8328SLionel Sambucin which case you get the entire pathname unmodified. 217757e8328SLionel SambucWhatever you end up with is looked for either in the current directory, 218757e8328SLionel Sambucor the directory specified by the 219757e8328SLionel Sambuc.Fl d 220757e8328SLionel Sambucoption. 221757e8328SLionel Sambuc.It Fl R , Fl Fl reverse 222757e8328SLionel SambucTells 223757e8328SLionel Sambuc.Nm 224757e8328SLionel Sambucthat this patch was created with the old and new files swapped. 225757e8328SLionel Sambuc(Yes, I'm afraid that does happen occasionally, human nature being what it 226757e8328SLionel Sambucis.) 227757e8328SLionel Sambuc.Nm 228757e8328SLionel Sambucwill attempt to swap each hunk around before applying it. 229757e8328SLionel SambucRejects will come out in the swapped format. 230757e8328SLionel SambucThe 231757e8328SLionel Sambuc.Fl R 232757e8328SLionel Sambucoption will not work with ed diff scripts because there is too little 233757e8328SLionel Sambucinformation to reconstruct the reverse operation. 234757e8328SLionel Sambuc.Pp 235757e8328SLionel SambucIf the first hunk of a patch fails, 236757e8328SLionel Sambuc.Nm 237757e8328SLionel Sambucwill reverse the hunk to see if it can be applied that way. 238757e8328SLionel SambucIf it can, you will be asked if you want to have the 239757e8328SLionel Sambuc.Fl R 240757e8328SLionel Sambucoption set. 241757e8328SLionel SambucIf it can't, the patch will continue to be applied normally. 242757e8328SLionel Sambuc(Note: this method cannot detect a reversed patch if it is a normal diff 243757e8328SLionel Sambucand if the first command is an append (i.e., it should have been a delete) 244757e8328SLionel Sambucsince appends always succeed, due to the fact that a null context will match 245757e8328SLionel Sambucanywhere. 246757e8328SLionel SambucLuckily, most patches add or change lines rather than delete them, so most 247757e8328SLionel Sambucreversed normal diffs will begin with a delete, which will fail, triggering 248757e8328SLionel Sambucthe heuristic.) 249757e8328SLionel Sambuc.It Fl r Ar rej-name , Fl Fl reject-file Ar rej-name 250757e8328SLionel SambucCauses the next argument to be interpreted as the reject file name. 251757e8328SLionel Sambuc.It Fl s , Fl Fl quiet , Fl Fl silent 252757e8328SLionel SambucMakes 253757e8328SLionel Sambuc.Nm 254757e8328SLionel Sambucdo its work silently, unless an error occurs. 255757e8328SLionel Sambuc.It Fl t , Fl Fl batch 256757e8328SLionel SambucSimilar to 257757e8328SLionel Sambuc.Fl f , 258757e8328SLionel Sambucin that it suppresses questions, but makes some different assumptions: 259757e8328SLionel Sambucskip patches for which a file to patch can't be found (the same as 260757e8328SLionel Sambuc.Fl f ) ; 261757e8328SLionel Sambucskip patches for which the file has the wrong version for the 262757e8328SLionel Sambuc.Qq Prereq: 263757e8328SLionel Sambucline in the patch; 264757e8328SLionel Sambucand assume that patches are reversed if they look like they are. 265757e8328SLionel Sambuc.It Fl u , Fl Fl unified 266757e8328SLionel SambucForces 267757e8328SLionel Sambuc.Nm 268757e8328SLionel Sambucto interpret the patch file as a unified context diff (a unidiff). 269*0a6a1f1dSLionel Sambuc.It Fl V Cm t | nil | never | none , Fl Fl version-control Cm t | nil | never | none 270757e8328SLionel SambucCauses the next argument to be interpreted as a method for creating 271757e8328SLionel Sambucbackup file names. 272757e8328SLionel SambucThe type of backups made can also be given in the 273757e8328SLionel Sambuc.Ev PATCH_VERSION_CONTROL 274757e8328SLionel Sambucor 275757e8328SLionel Sambuc.Ev VERSION_CONTROL 276757e8328SLionel Sambucenvironment variables, which are overridden by this option. 277757e8328SLionel SambucThe 278757e8328SLionel Sambuc.Fl B 279757e8328SLionel Sambucoption overrides this option, causing the prefix to always be used for 280757e8328SLionel Sambucmaking backup file names. 281757e8328SLionel SambucThe values of the 282757e8328SLionel Sambuc.Ev PATCH_VERSION_CONTROL 283757e8328SLionel Sambucand 284757e8328SLionel Sambuc.Ev VERSION_CONTROL 285757e8328SLionel Sambucenvironment variables and the argument to the 286757e8328SLionel Sambuc.Fl V 287757e8328SLionel Sambucoption are like the GNU Emacs 288757e8328SLionel Sambuc.Dq version-control 289757e8328SLionel Sambucvariable; they also recognize synonyms that are more descriptive. 290757e8328SLionel SambucThe valid values are (unique abbreviations are accepted): 291757e8328SLionel Sambuc.Bl -tag -width Ds -offset indent 292757e8328SLionel Sambuc.It Cm t , numbered 293757e8328SLionel SambucAlways make numbered backups. 294757e8328SLionel Sambuc.It Cm nil , existing 295757e8328SLionel SambucMake numbered backups of files that already have them, 296757e8328SLionel Sambucsimple backups of the others. 297757e8328SLionel Sambuc.It Cm never , simple 298757e8328SLionel SambucAlways make simple backups. 299757e8328SLionel Sambuc.El 300757e8328SLionel Sambuc.It Fl v , Fl Fl version 301757e8328SLionel SambucCauses 302757e8328SLionel Sambuc.Nm 303757e8328SLionel Sambucto print out its revision header and patch level. 304757e8328SLionel Sambuc.It Fl x Ar number , Fl Fl debug Ar number 305757e8328SLionel SambucSets internal debugging flags, and is of interest only to 306757e8328SLionel Sambuc.Nm 307757e8328SLionel Sambucpatchers. 308757e8328SLionel Sambuc.It Fl z Ar backup-ext , Fl Fl suffix Ar backup-ext 309757e8328SLionel SambucCauses the next argument to be interpreted as the backup extension, to be 310757e8328SLionel Sambucused in place of 311757e8328SLionel Sambuc.Qq .orig . 312757e8328SLionel Sambuc.It Fl Fl posix 313757e8328SLionel SambucEnables strict 314757e8328SLionel Sambuc.St -p1003.1-2004 315757e8328SLionel Sambucconformance, specifically: 316757e8328SLionel Sambuc.Bl -enum 317757e8328SLionel Sambuc.It 318757e8328SLionel SambucBackup files are not created unless the 319757e8328SLionel Sambuc.Fl b 320757e8328SLionel Sambucoption is specified. 321757e8328SLionel Sambuc.It 322757e8328SLionel SambucIf unspecified, the file name used is the first of the old, new and 323757e8328SLionel Sambucindex files that exists. 324757e8328SLionel Sambuc.El 325757e8328SLionel Sambuc.El 326757e8328SLionel Sambuc.Ss Patch Application 327757e8328SLionel Sambuc.Nm 328757e8328SLionel Sambucwill try to skip any leading garbage, apply the diff, 329757e8328SLionel Sambucand then skip any trailing garbage. 330757e8328SLionel SambucThus you could feed an article or message containing a 331757e8328SLionel Sambucdiff listing to 332757e8328SLionel Sambuc.Nm , 333757e8328SLionel Sambucand it should work. 334757e8328SLionel SambucIf the entire diff is indented by a consistent amount, 335757e8328SLionel Sambucthis will be taken into account. 336757e8328SLionel Sambuc.Pp 337757e8328SLionel SambucWith context diffs, and to a lesser extent with normal diffs, 338757e8328SLionel Sambuc.Nm 339757e8328SLionel Sambuccan detect when the line numbers mentioned in the patch are incorrect, 340757e8328SLionel Sambucand will attempt to find the correct place to apply each hunk of the patch. 341757e8328SLionel SambucAs a first guess, it takes the line number mentioned for the hunk, plus or 342757e8328SLionel Sambucminus any offset used in applying the previous hunk. 343757e8328SLionel SambucIf that is not the correct place, 344757e8328SLionel Sambuc.Nm 345757e8328SLionel Sambucwill scan both forwards and backwards for a set of lines matching the context 346757e8328SLionel Sambucgiven in the hunk. 347757e8328SLionel SambucFirst 348757e8328SLionel Sambuc.Nm 349757e8328SLionel Sambuclooks for a place where all lines of the context match. 350757e8328SLionel SambucIf no such place is found, and it's a context diff, and the maximum fuzz factor 351757e8328SLionel Sambucis set to 1 or more, then another scan takes place ignoring the first and last 352757e8328SLionel Sambucline of context. 353757e8328SLionel SambucIf that fails, and the maximum fuzz factor is set to 2 or more, 354757e8328SLionel Sambucthe first two and last two lines of context are ignored, 355757e8328SLionel Sambucand another scan is made. 356757e8328SLionel Sambuc.Pq The default maximum fuzz factor is 2. 357757e8328SLionel Sambuc.Pp 358757e8328SLionel SambucIf 359757e8328SLionel Sambuc.Nm 360757e8328SLionel Sambuccannot find a place to install that hunk of the patch, it will put the hunk 361757e8328SLionel Sambucout to a reject file, which normally is the name of the output file plus 362757e8328SLionel Sambuc.Qq .rej . 363757e8328SLionel Sambuc(Note that the rejected hunk will come out in context diff form whether the 364757e8328SLionel Sambucinput patch was a context diff or a normal diff. 365757e8328SLionel SambucIf the input was a normal diff, many of the contexts will simply be null.) 366757e8328SLionel SambucThe line numbers on the hunks in the reject file may be different than 367757e8328SLionel Sambucin the patch file: they reflect the approximate location patch thinks the 368757e8328SLionel Sambucfailed hunks belong in the new file rather than the old one. 369757e8328SLionel Sambuc.Pp 370757e8328SLionel SambucAs each hunk is completed, you will be told whether the hunk succeeded or 371757e8328SLionel Sambucfailed, and which line (in the new file) 372757e8328SLionel Sambuc.Nm 373757e8328SLionel Sambucthought the hunk should go on. 374757e8328SLionel SambucIf this is different from the line number specified in the diff, 375757e8328SLionel Sambucyou will be told the offset. 376757e8328SLionel SambucA single large offset MAY be an indication that a hunk was installed in the 377757e8328SLionel Sambucwrong place. 378757e8328SLionel SambucYou will also be told if a fuzz factor was used to make the match, in which 379757e8328SLionel Sambuccase you should also be slightly suspicious. 380757e8328SLionel Sambuc.Ss Filename Determination 381757e8328SLionel SambucIf no original file is specified on the command line, 382757e8328SLionel Sambuc.Nm 383757e8328SLionel Sambucwill try to figure out from the leading garbage what the name of the file 384757e8328SLionel Sambucto edit is. 385757e8328SLionel SambucWhen checking a prospective file name, pathname components are stripped 386757e8328SLionel Sambucas specified by the 387757e8328SLionel Sambuc.Fl p 388757e8328SLionel Sambucoption and the file's existence and writability are checked relative 389757e8328SLionel Sambucto the current working directory (or the directory specified by the 390757e8328SLionel Sambuc.Fl d 391757e8328SLionel Sambucoption). 392757e8328SLionel Sambuc.Pp 393757e8328SLionel SambucIf the diff is a context or unified diff, 394757e8328SLionel Sambuc.Nm 395757e8328SLionel Sambucis able to determine the old and new file names from the diff header. 396757e8328SLionel SambucFor context diffs, the 397757e8328SLionel Sambuc.Dq old 398757e8328SLionel Sambucfile is specified in the line beginning with 399757e8328SLionel Sambuc.Qq *** 400757e8328SLionel Sambucand the 401757e8328SLionel Sambuc.Dq new 402757e8328SLionel Sambucfile is specified in the line beginning with 403757e8328SLionel Sambuc.Qq --- . 404757e8328SLionel SambucFor a unified diff, the 405757e8328SLionel Sambuc.Dq old 406757e8328SLionel Sambucfile is specified in the line beginning with 407757e8328SLionel Sambuc.Qq --- 408757e8328SLionel Sambucand the 409757e8328SLionel Sambuc.Dq new 410757e8328SLionel Sambucfile is specified in the line beginning with 411757e8328SLionel Sambuc.Qq +++ . 412757e8328SLionel SambucIf there is an 413757e8328SLionel Sambuc.Qq Index: 414757e8328SLionel Sambucline in the leading garbage (regardless of the diff type), 415757e8328SLionel Sambuc.Nm 416757e8328SLionel Sambucwill use the file name from that line as the 417757e8328SLionel Sambuc.Dq index 418757e8328SLionel Sambucfile. 419757e8328SLionel Sambuc.Pp 420757e8328SLionel Sambuc.Nm 421757e8328SLionel Sambucwill choose the file name by performing the following steps, with the first 422757e8328SLionel Sambucmatch used: 423757e8328SLionel Sambuc.Bl -enum 424757e8328SLionel Sambuc.It 425757e8328SLionel SambucIf 426757e8328SLionel Sambuc.Nm 427757e8328SLionel Sambucis operating in strict 428757e8328SLionel Sambuc.St -p1003.1-2004 429757e8328SLionel Sambucmode, the first of the 430757e8328SLionel Sambuc.Dq old , 431757e8328SLionel Sambuc.Dq new 432757e8328SLionel Sambucand 433757e8328SLionel Sambuc.Dq index 434757e8328SLionel Sambucfile names that exist is used. 435757e8328SLionel SambucOtherwise, 436757e8328SLionel Sambuc.Nm 437757e8328SLionel Sambucwill examine either the 438757e8328SLionel Sambuc.Dq old 439757e8328SLionel Sambucand 440757e8328SLionel Sambuc.Dq new 441757e8328SLionel Sambucfile names or, for a non-context diff, the 442757e8328SLionel Sambuc.Dq index 443757e8328SLionel Sambucfile name, and choose the file name with the fewest path components, 444757e8328SLionel Sambucthe shortest basename, and the shortest total file name length (in that order). 445757e8328SLionel Sambuc.It 446757e8328SLionel SambucIf no file exists, 447757e8328SLionel Sambuc.Nm 448*0a6a1f1dSLionel Sambucchecks for the existence of the files in an RCS directory using the criteria 449*0a6a1f1dSLionel Sambucspecified above. 450757e8328SLionel SambucIf found, 451757e8328SLionel Sambuc.Nm 452757e8328SLionel Sambucwill attempt to get or check out the file. 453757e8328SLionel Sambuc.It 454757e8328SLionel SambucIf no suitable file was found to patch, the patch file is a context or 455757e8328SLionel Sambucunified diff, and the old file was zero length, the new file name is 456757e8328SLionel Sambuccreated and used. 457757e8328SLionel Sambuc.It 458757e8328SLionel SambucIf the file name still cannot be determined, 459757e8328SLionel Sambuc.Nm 460757e8328SLionel Sambucwill prompt the user for the file name to use. 461757e8328SLionel Sambuc.El 462757e8328SLionel Sambuc.Pp 463757e8328SLionel SambucAdditionally, if the leading garbage contains a 464757e8328SLionel Sambuc.Qq Prereq:\ \& 465757e8328SLionel Sambucline, 466757e8328SLionel Sambuc.Nm 467757e8328SLionel Sambucwill take the first word from the prerequisites line (normally a version 468757e8328SLionel Sambucnumber) and check the input file to see if that word can be found. 469757e8328SLionel SambucIf not, 470757e8328SLionel Sambuc.Nm 471757e8328SLionel Sambucwill ask for confirmation before proceeding. 472757e8328SLionel Sambuc.Pp 473757e8328SLionel SambucThe upshot of all this is that you should be able to say, while in a news 474757e8328SLionel Sambucinterface, the following: 475757e8328SLionel Sambuc.Pp 476757e8328SLionel Sambuc.Dl | patch -d /usr/src/local/blurfl 477757e8328SLionel Sambuc.Pp 478757e8328SLionel Sambucand patch a file in the blurfl directory directly from the article containing 479757e8328SLionel Sambucthe patch. 480757e8328SLionel Sambuc.Ss Backup Files 481757e8328SLionel SambucBy default, the patched version is put in place of the original, with 482757e8328SLionel Sambucthe original file backed up to the same name with the extension 483757e8328SLionel Sambuc.Qq .orig , 484757e8328SLionel Sambucor as specified by the 485757e8328SLionel Sambuc.Fl B , 486757e8328SLionel Sambuc.Fl V , 487757e8328SLionel Sambucor 488757e8328SLionel Sambuc.Fl z 489757e8328SLionel Sambucoptions. 490757e8328SLionel SambucThe extension used for making backup files may also be specified in the 491757e8328SLionel Sambuc.Ev SIMPLE_BACKUP_SUFFIX 492757e8328SLionel Sambucenvironment variable, which is overridden by the options above. 493757e8328SLionel Sambuc.Pp 494757e8328SLionel SambucIf the backup file is a symbolic or hard link to the original file, 495757e8328SLionel Sambuc.Nm 496757e8328SLionel Sambuccreates a new backup file name by changing the first lowercase letter 497757e8328SLionel Sambucin the last component of the file's name into uppercase. 498757e8328SLionel SambucIf there are no more lowercase letters in the name, 499757e8328SLionel Sambucit removes the first character from the name. 500757e8328SLionel SambucIt repeats this process until it comes up with a 501757e8328SLionel Sambucbackup file that does not already exist or is not linked to the original file. 502757e8328SLionel Sambuc.Pp 503757e8328SLionel SambucYou may also specify where you want the output to go with the 504757e8328SLionel Sambuc.Fl o 505757e8328SLionel Sambucoption; if that file already exists, it is backed up first. 506757e8328SLionel Sambuc.Ss Notes For Patch Senders 507757e8328SLionel SambucThere are several things you should bear in mind if you are going to 508757e8328SLionel Sambucbe sending out patches: 509757e8328SLionel Sambuc.Pp 510757e8328SLionel SambucFirst, you can save people a lot of grief by keeping a 511757e8328SLionel Sambuc.Pa patchlevel.h 512757e8328SLionel Sambucfile which is patched to increment the patch level as the first diff in the 513757e8328SLionel Sambucpatch file you send out. 514757e8328SLionel SambucIf you put a 515757e8328SLionel Sambuc.Qq Prereq: 516757e8328SLionel Sambucline in with the patch, it won't let them apply 517757e8328SLionel Sambucpatches out of order without some warning. 518757e8328SLionel Sambuc.Pp 519757e8328SLionel SambucSecond, make sure you've specified the file names right, either in a 520757e8328SLionel Sambuccontext diff header, or with an 521757e8328SLionel Sambuc.Qq Index: 522757e8328SLionel Sambucline. 523757e8328SLionel SambucIf you are patching something in a subdirectory, be sure to tell the patch 524757e8328SLionel Sambucuser to specify a 525757e8328SLionel Sambuc.Fl p 526757e8328SLionel Sambucoption as needed. 527757e8328SLionel Sambuc.Pp 528757e8328SLionel SambucThird, you can create a file by sending out a diff that compares a 529757e8328SLionel Sambucnull file to the file you want to create. 530757e8328SLionel SambucThis will only work if the file you want to create doesn't exist already in 531757e8328SLionel Sambucthe target directory. 532757e8328SLionel Sambuc.Pp 533757e8328SLionel SambucFourth, take care not to send out reversed patches, since it makes people wonder 534757e8328SLionel Sambucwhether they already applied the patch. 535757e8328SLionel Sambuc.Pp 536757e8328SLionel SambucFifth, while you may be able to get away with putting 582 diff listings into 537757e8328SLionel Sambucone file, it is probably wiser to group related patches into separate files in 538757e8328SLionel Sambuccase something goes haywire. 539757e8328SLionel Sambuc.Sh ENVIRONMENT 540757e8328SLionel Sambuc.Bl -tag -width "PATCH_VERSION_CONTROL" -compact 541757e8328SLionel Sambuc.It Ev POSIXLY_CORRECT 542757e8328SLionel SambucWhen set, 543757e8328SLionel Sambuc.Nm 544757e8328SLionel Sambucbehaves as if the 545757e8328SLionel Sambuc.Fl Fl posix 546757e8328SLionel Sambucoption has been specified. 547757e8328SLionel Sambuc.It Ev SIMPLE_BACKUP_SUFFIX 548757e8328SLionel SambucExtension to use for backup file names instead of 549757e8328SLionel Sambuc.Qq .orig . 550757e8328SLionel Sambuc.It Ev TMPDIR 551757e8328SLionel SambucDirectory to put temporary files in; default is 552757e8328SLionel Sambuc.Pa /tmp . 553757e8328SLionel Sambuc.It Ev PATCH_VERSION_CONTROL 554757e8328SLionel SambucSelects when numbered backup files are made. 555757e8328SLionel Sambuc.It Ev VERSION_CONTROL 556757e8328SLionel SambucSame as 557757e8328SLionel Sambuc.Ev PATCH_VERSION_CONTROL . 558757e8328SLionel Sambuc.El 559757e8328SLionel Sambuc.Sh FILES 560757e8328SLionel Sambuc.Bl -tag -width "$TMPDIR/patch*" -compact 561757e8328SLionel Sambuc.It Pa $TMPDIR/patch* 562757e8328SLionel Sambuc.Nm 563757e8328SLionel Sambuctemporary files 564757e8328SLionel Sambuc.It Pa /dev/tty 565757e8328SLionel Sambucused to read input when 566757e8328SLionel Sambuc.Nm 567757e8328SLionel Sambucprompts the user 568757e8328SLionel Sambuc.El 569757e8328SLionel Sambuc.Sh DIAGNOSTICS 570757e8328SLionel SambucToo many to list here, but generally indicative that 571757e8328SLionel Sambuc.Nm 572757e8328SLionel Sambuccouldn't parse your patch file. 573757e8328SLionel Sambuc.Pp 574757e8328SLionel SambucThe message 575757e8328SLionel Sambuc.Qq Hmm... 576757e8328SLionel Sambucindicates that there is unprocessed text in the patch file and that 577757e8328SLionel Sambuc.Nm 578757e8328SLionel Sambucis attempting to intuit whether there is a patch in that text and, if so, 579757e8328SLionel Sambucwhat kind of patch it is. 580757e8328SLionel Sambuc.Pp 581757e8328SLionel SambucThe 582757e8328SLionel Sambuc.Nm 583757e8328SLionel Sambucutility exits with one of the following values: 584757e8328SLionel Sambuc.Pp 585757e8328SLionel Sambuc.Bl -tag -width Ds -compact -offset indent 586757e8328SLionel Sambuc.It \&0 587757e8328SLionel SambucSuccessful completion. 588757e8328SLionel Sambuc.It \&1 589757e8328SLionel SambucOne or more lines were written to a reject file. 590757e8328SLionel Sambuc.It \*[Gt]\&1 591757e8328SLionel SambucAn error occurred. 592757e8328SLionel Sambuc.El 593757e8328SLionel Sambuc.Pp 594757e8328SLionel SambucWhen applying a set of patches in a loop it behooves you to check this 595757e8328SLionel Sambucexit status so you don't apply a later patch to a partially patched file. 596757e8328SLionel Sambuc.Sh SEE ALSO 597757e8328SLionel Sambuc.Xr diff 1 598757e8328SLionel Sambuc.Sh STANDARDS 599757e8328SLionel SambucThe 600757e8328SLionel Sambuc.Nm 601757e8328SLionel Sambucutility is compliant with the 602757e8328SLionel Sambuc.St -p1003.1-2004 603757e8328SLionel Sambucspecification 604757e8328SLionel Sambuc(except as detailed above for the 605757e8328SLionel Sambuc.Fl -posix 606757e8328SLionel Sambucoption), 607757e8328SLionel Sambucthough the presence of 608757e8328SLionel Sambuc.Nm 609757e8328SLionel Sambucitself is optional. 610757e8328SLionel Sambuc.Pp 611757e8328SLionel SambucThe flags 612757e8328SLionel Sambuc.Op Fl CEfstuvBFVxz 613757e8328SLionel Sambucand 614757e8328SLionel Sambuc.Op Fl -posix 615757e8328SLionel Sambucare extensions to that specification. 616757e8328SLionel Sambuc.Sh AUTHORS 617757e8328SLionel Sambuc.An Larry Wall 618757e8328SLionel Sambucwith many other contributors. 619757e8328SLionel Sambuc.Sh CAVEATS 620757e8328SLionel Sambuc.Nm 621757e8328SLionel Sambuccannot tell if the line numbers are off in an ed script, and can only detect 622757e8328SLionel Sambucbad line numbers in a normal diff when it finds a 623757e8328SLionel Sambuc.Qq change 624757e8328SLionel Sambucor a 625757e8328SLionel Sambuc.Qq delete 626757e8328SLionel Sambuccommand. 627757e8328SLionel SambucA context diff using fuzz factor 3 may have the same problem. 628757e8328SLionel SambucUntil a suitable interactive interface is added, you should probably do 629757e8328SLionel Sambuca context diff in these cases to see if the changes made sense. 630757e8328SLionel SambucOf course, compiling without errors is a pretty good indication that the patch 631757e8328SLionel Sambucworked, but not always. 632757e8328SLionel Sambuc.Pp 633757e8328SLionel Sambuc.Nm 634757e8328SLionel Sambucusually produces the correct results, even when it has to do a lot of 635757e8328SLionel Sambucguessing. 636757e8328SLionel SambucHowever, the results are guaranteed to be correct only when the patch is 637757e8328SLionel Sambucapplied to exactly the same version of the file that the patch was 638757e8328SLionel Sambucgenerated from. 639757e8328SLionel Sambuc.Sh BUGS 640757e8328SLionel SambucCould be smarter about partial matches, excessively deviant offsets and 641757e8328SLionel Sambucswapped code, but that would take an extra pass. 642757e8328SLionel Sambuc.Pp 643757e8328SLionel SambucCheck patch mode 644757e8328SLionel Sambuc.Pq Fl C 645757e8328SLionel Sambucwill fail if you try to check several patches in succession that build on 646757e8328SLionel Sambuceach other. 647757e8328SLionel SambucThe entire 648757e8328SLionel Sambuc.Nm 649757e8328SLionel Sambuccode would have to be restructured to keep temporary files around so that it 650757e8328SLionel Sambuccan handle this situation. 651757e8328SLionel Sambuc.Pp 652757e8328SLionel SambucIf code has been duplicated (for instance with #ifdef OLDCODE ... #else ... 653757e8328SLionel Sambuc#endif), 654757e8328SLionel Sambuc.Nm 655757e8328SLionel Sambucis incapable of patching both versions, and, if it works at all, will likely 656757e8328SLionel Sambucpatch the wrong one, and tell you that it succeeded to boot. 657757e8328SLionel Sambuc.Pp 658757e8328SLionel SambucIf you apply a patch you've already applied, 659757e8328SLionel Sambuc.Nm 660757e8328SLionel Sambucwill think it is a reversed patch, and offer to un-apply the patch. 661757e8328SLionel SambucThis could be construed as a feature. 662