| 1 | .\" $OpenBSD: patch.1,v 1.17 2003/10/31 20:20:45 millert Exp $ |
| 2 | .\" $DragonFly: src/usr.bin/patch/patch.1,v 1.4 2004/12/26 18:58:59 swildner Exp $ |
| 3 | .\" |
| 4 | .\" Copyright 1986, Larry Wall |
| 5 | .\" |
| 6 | .\" Redistribution and use in source and binary forms, with or without |
| 7 | .\" modification, are permitted provided that the following condition |
| 8 | .\" is met: |
| 9 | .\" 1. Redistributions of source code must retain the above copyright |
| 10 | .\" notice, this condition and the following disclaimer. |
| 11 | .\" |
| 12 | .\" THIS SOFTWARE IS PROVIDED BY THE AUTHOR AND CONTRIBUTORS ``AS IS'' AND |
| 13 | .\" ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE |
| 14 | .\" IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE |
| 15 | .\" ARE DISCLAIMED. IN NO EVENT SHALL THE AUTHOR OR CONTRIBUTORS BE LIABLE |
| 16 | .\" FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR CONSEQUENTIAL |
| 17 | .\" DAMAGES (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS |
| 18 | .\" OR SERVICES; LOSS OF USE, DATA, OR PROFITS; OR BUSINESS INTERRUPTION) |
| 19 | .\" HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT |
| 20 | .\" LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY |
| 21 | .\" OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF |
| 22 | .\" SUCH DAMAGE. |
| 23 | .\" |
| 24 | .Dd July 23, 2003 |
| 25 | .Dt PATCH 1 |
| 26 | .Os |
| 27 | .Sh NAME |
| 28 | .Nm patch |
| 29 | .Nd apply a diff file to an original |
| 30 | .Sh SYNOPSIS |
| 31 | .Nm patch |
| 32 | .Op Cm options |
| 33 | .Op Ar origfile Op Ar patchfile |
| 34 | .Nm patch |
| 35 | .Pf \*(Lt Ar patchfile |
| 36 | .Sh DESCRIPTION |
| 37 | .Nm |
| 38 | will take a patch file containing any of the four forms of difference |
| 39 | listing produced by the |
| 40 | .Xr diff 1 |
| 41 | program and apply those differences to an original file, |
| 42 | producing a patched version. |
| 43 | If |
| 44 | .Ar patchfile |
| 45 | is omitted, or is a hyphen, the patch will be read from the standard input. |
| 46 | .Pp |
| 47 | .Nm |
| 48 | will attempt to determine the type of the diff listing, unless over-ruled by a |
| 49 | .Fl c , |
| 50 | .Fl e , |
| 51 | .Fl n , |
| 52 | or |
| 53 | .Fl u |
| 54 | option. |
| 55 | Context diffs (old-style, new-style, and unified) and |
| 56 | normal diffs are applied directly by the |
| 57 | .Nm |
| 58 | program itself, whereas ed diffs are simply fed to the |
| 59 | .Xr ed 1 |
| 60 | editor via a pipe. |
| 61 | .Pp |
| 62 | If the |
| 63 | .Ar patchfile |
| 64 | contains more than one patch, |
| 65 | .Nm |
| 66 | will try to apply each of them as if they came from separate patch files. |
| 67 | This means, among other things, that it is assumed that the name of the file |
| 68 | to patch must be determined for each diff listing, and that the garbage before |
| 69 | each diff listing will be examined for interesting things such as file names |
| 70 | and revision level (see the section on |
| 71 | .Sx Filename Determination |
| 72 | below). |
| 73 | .Pp |
| 74 | The options are as follows: |
| 75 | .Bl -tag -width Ds |
| 76 | .It Fl b , Fl Fl backup |
| 77 | Save a backup copy of the file before it is modified. |
| 78 | By default the original file is saved with a backup extension of |
| 79 | .Qq .orig |
| 80 | unless the file already has a numbered backup, in which case a numbered |
| 81 | backup is made. |
| 82 | This is equivalent to specifying |
| 83 | .Qo Fl V Ar existing Qc . |
| 84 | This option is currently the default but that will change in a future release. |
| 85 | .It Fl B , Fl Fl prefix |
| 86 | Causes the next argument to be interpreted as a prefix to the backup file |
| 87 | name. |
| 88 | If this argument is specified, any argument to |
| 89 | .Fl z |
| 90 | will be ignored. |
| 91 | .It Fl c , Fl Fl context |
| 92 | Forces |
| 93 | .Nm |
| 94 | to interpret the patch file as a context diff. |
| 95 | .It Fl C , Fl Fl check |
| 96 | Checks that the patch would apply cleanly, but does not modify anything. |
| 97 | .It Fl d , Fl Fl directory |
| 98 | Causes |
| 99 | .Nm |
| 100 | to interpret the next argument as a directory, and |
| 101 | .Xr cd 1 |
| 102 | to it before doing anything else. |
| 103 | .It Fl D , Fl Fl ifdef |
| 104 | Causes |
| 105 | .Nm |
| 106 | to use the |
| 107 | .Qq #ifdef...#endif |
| 108 | construct to mark changes. |
| 109 | The argument following will be used as the differentiating symbol. |
| 110 | Note that, unlike the C compiler, there must be a space between the |
| 111 | .Fl D |
| 112 | and the argument. |
| 113 | .It Fl e , Fl Fl ed |
| 114 | Forces |
| 115 | .Nm |
| 116 | to interpret the patch file as an |
| 117 | .Xr ed 1 |
| 118 | script. |
| 119 | .It Fl E , Fl Fl remove-empty-files |
| 120 | Causes |
| 121 | .Nm |
| 122 | to remove output files that are empty after the patches have been applied. |
| 123 | This option is useful when applying patches that create or remove files. |
| 124 | .It Fl f , Fl Fl force |
| 125 | Forces |
| 126 | .Nm |
| 127 | to assume that the user knows exactly what he or she is doing, and to not |
| 128 | ask any questions. |
| 129 | It assumes the following: |
| 130 | skip patches for which a file to patch can't be found; |
| 131 | patch files even though they have the wrong version for the |
| 132 | .Qq Prereq: |
| 133 | line in the patch; |
| 134 | and assume that patches are not reversed even if they look like they are. |
| 135 | This option does not suppress commentary; use |
| 136 | .Fl s |
| 137 | for that. |
| 138 | .It Xo |
| 139 | .Fl F Ns Aq Ar number , |
| 140 | .Fl Fl fuzz Aq Ar number |
| 141 | .Xc |
| 142 | Sets the maximum fuzz factor. |
| 143 | This option only applies to context diffs, and causes |
| 144 | .Nm |
| 145 | to ignore up to that many lines in looking for places to install a hunk. |
| 146 | Note that a larger fuzz factor increases the odds of a faulty patch. |
| 147 | The default fuzz factor is 2, and it may not be set to more than |
| 148 | the number of lines of context in the context diff, ordinarily 3. |
| 149 | .It Fl i , Fl Fl input |
| 150 | Causes the next argument to be interpreted as the input file name |
| 151 | (i.e. a patchfile). |
| 152 | This option may be specified multiple times. |
| 153 | .It Fl l , Fl Fl ignore-whitespace |
| 154 | Causes the pattern matching to be done loosely, in case the tabs and |
| 155 | spaces have been munged in your input file. |
| 156 | Any sequence of whitespace in the pattern line will match any sequence |
| 157 | in the input file. |
| 158 | Normal characters must still match exactly. |
| 159 | Each line of the context must still match a line in the input file. |
| 160 | .It Fl n , Fl Fl normal |
| 161 | Forces |
| 162 | .Nm |
| 163 | to interpret the patch file as a normal diff. |
| 164 | .It Fl N , Fl Fl forward |
| 165 | Causes |
| 166 | .Nm |
| 167 | to ignore patches that it thinks are reversed or already applied. |
| 168 | See also |
| 169 | .Fl R . |
| 170 | .It Fl o , Fl Fl output |
| 171 | Causes the next argument to be interpreted as the output file name. |
| 172 | .It Xo |
| 173 | .Fl p Ns Aq Ar number , |
| 174 | .Fl Fl strip Aq Ar number |
| 175 | .Xc |
| 176 | Sets the pathname strip count, |
| 177 | which controls how pathnames found in the patch file are treated, |
| 178 | in case you keep your files in a different directory than the person who sent |
| 179 | out the patch. |
| 180 | The strip count specifies how many slashes are to be stripped from |
| 181 | the front of the pathname. |
| 182 | (Any intervening directory names also go away.) |
| 183 | For example, supposing the file name in the patch file was |
| 184 | .Pa /u/howard/src/blurfl/blurfl.c : |
| 185 | .Pp |
| 186 | Setting |
| 187 | .Fl p Ns Ar 0 |
| 188 | gives the entire pathname unmodified. |
| 189 | .Pp |
| 190 | .Fl p Ns Ar 1 |
| 191 | gives |
| 192 | .Pp |
| 193 | .D1 Pa u/howard/src/blurfl/blurfl.c |
| 194 | .Pp |
| 195 | without the leading slash. |
| 196 | .Pp |
| 197 | .Fl p Ns Ar 4 |
| 198 | gives |
| 199 | .Pp |
| 200 | .D1 Pa blurfl/blurfl.c |
| 201 | .Pp |
| 202 | Not specifying |
| 203 | .Fl p |
| 204 | at all just gives you |
| 205 | .Pa blurfl.c , |
| 206 | unless all of the directories in the leading path |
| 207 | .Pq Pa u/howard/src/blurfl |
| 208 | exist and that path is relative, |
| 209 | in which case you get the entire pathname unmodified. |
| 210 | Whatever you end up with is looked for either in the current directory, |
| 211 | or the directory specified by the |
| 212 | .Fl d |
| 213 | option. |
| 214 | .It Fl r , Fl Fl reject-file |
| 215 | Causes the next argument to be interpreted as the reject file name. |
| 216 | .It Fl R , Fl Fl reverse |
| 217 | Tells |
| 218 | .Nm |
| 219 | that this patch was created with the old and new files swapped. |
| 220 | (Yes, I'm afraid that does happen occasionally, human nature being what it |
| 221 | is.) |
| 222 | .Nm |
| 223 | will attempt to swap each hunk around before applying it. |
| 224 | Rejects will come out in the swapped format. |
| 225 | The |
| 226 | .Fl R |
| 227 | option will not work with ed diff scripts because there is too little |
| 228 | information to reconstruct the reverse operation. |
| 229 | .Pp |
| 230 | If the first hunk of a patch fails, |
| 231 | .Nm |
| 232 | will reverse the hunk to see if it can be applied that way. |
| 233 | If it can, you will be asked if you want to have the |
| 234 | .Fl R |
| 235 | option set. |
| 236 | If it can't, the patch will continue to be applied normally. |
| 237 | (Note: this method cannot detect a reversed patch if it is a normal diff |
| 238 | and if the first command is an append (i.e. it should have been a delete) |
| 239 | since appends always succeed, due to the fact that a null context will match |
| 240 | anywhere. |
| 241 | Luckily, most patches add or change lines rather than delete them, so most |
| 242 | reversed normal diffs will begin with a delete, which will fail, triggering |
| 243 | the heuristic.) |
| 244 | .It Xo |
| 245 | .Fl s , Fl Fl quiet , |
| 246 | .Fl Fl silent |
| 247 | .Xc |
| 248 | Makes |
| 249 | .Nm |
| 250 | do its work silently, unless an error occurs. |
| 251 | .It Fl t , Fl Fl batch |
| 252 | Similar to |
| 253 | .Fl f , |
| 254 | in that it suppresses questions, but makes some different assumptions: |
| 255 | skip patches for which a file to patch can't be found (the same as |
| 256 | .Fl f ) ; |
| 257 | skip patches for which the file has the wrong version for the |
| 258 | .Qq Prereq: |
| 259 | line in the patch; |
| 260 | and assume that patches are reversed if they look like they are. |
| 261 | .It Fl u , Fl Fl unified |
| 262 | Forces |
| 263 | .Nm |
| 264 | to interpret the patch file as a unified context diff (a unidiff). |
| 265 | .It Fl v , Fl Fl version |
| 266 | Causes |
| 267 | .Nm |
| 268 | to print out its revision header and patch level. |
| 269 | .It Fl V , Fl Fl version-control |
| 270 | Causes the next argument to be interpreted as a method for creating |
| 271 | backup file names. |
| 272 | The type of backups made can also be given in the |
| 273 | .Ev PATCH_VERSION_CONTROL |
| 274 | or |
| 275 | .Ev VERSION_CONTROL |
| 276 | environment variables, which are overridden by this option. |
| 277 | The |
| 278 | .Fl B |
| 279 | option overrides this option, causing the prefix to always be used for |
| 280 | making backup file names. |
| 281 | The values of the |
| 282 | .Ev PATCH_VERSION_CONTROL |
| 283 | and |
| 284 | .Ev VERSION_CONTROL |
| 285 | environment variables and the argument to the |
| 286 | .Fl V |
| 287 | option are like the GNU Emacs |
| 288 | .Dq version-control |
| 289 | variable; they also recognize synonyms that are more descriptive. |
| 290 | The valid values are (unique abbreviations are accepted): |
| 291 | .Bl -tag -width Ds -offset indent |
| 292 | .It t , numbered |
| 293 | Always make numbered backups. |
| 294 | .It nil , existing |
| 295 | Make numbered backups of files that already have them, |
| 296 | simple backups of the others. |
| 297 | .It never , simple |
| 298 | Always make simple backups. |
| 299 | .El |
| 300 | .It Xo |
| 301 | .Fl x Ns Aq Ar number , |
| 302 | .Fl Fl debug Aq Ar number |
| 303 | .Xc |
| 304 | Sets internal debugging flags, and is of interest only to |
| 305 | .Nm |
| 306 | patchers. |
| 307 | .It Fl z , Fl Fl suffix |
| 308 | Causes the next argument to be interpreted as the backup extension, to be |
| 309 | used in place of |
| 310 | .Qq .orig . |
| 311 | .It Fl Fl posix |
| 312 | Enables strict |
| 313 | .St -p1003.2 |
| 314 | conformance, specifically: |
| 315 | .Bl -enum |
| 316 | .It |
| 317 | Backup files are not created unless the |
| 318 | .Fl b |
| 319 | option is specified. |
| 320 | .It |
| 321 | If unspecified, the file name used is the first of the old, new and |
| 322 | index files that exists. |
| 323 | .El |
| 324 | .El |
| 325 | .Ss Patch Application |
| 326 | .Nm |
| 327 | will try to skip any leading garbage, apply the diff, |
| 328 | and then skip any trailing garbage. |
| 329 | Thus you could feed an article or message containing a |
| 330 | diff listing to |
| 331 | .Nm patch , |
| 332 | and it should work. |
| 333 | If the entire diff is indented by a consistent amount, |
| 334 | this will be taken into account. |
| 335 | .Pp |
| 336 | With context diffs, and to a lesser extent with normal diffs, |
| 337 | .Nm |
| 338 | can detect when the line numbers mentioned in the patch are incorrect, |
| 339 | and will attempt to find the correct place to apply each hunk of the patch. |
| 340 | As a first guess, it takes the line number mentioned for the hunk, plus or |
| 341 | minus any offset used in applying the previous hunk. |
| 342 | If that is not the correct place, |
| 343 | .Nm |
| 344 | will scan both forwards and backwards for a set of lines matching the context |
| 345 | given in the hunk. |
| 346 | First |
| 347 | .Nm |
| 348 | looks for a place where all lines of the context match. |
| 349 | If no such place is found, and it's a context diff, and the maximum fuzz factor |
| 350 | is set to 1 or more, then another scan takes place ignoring the first and last |
| 351 | line of context. |
| 352 | If that fails, and the maximum fuzz factor is set to 2 or more, |
| 353 | the first two and last two lines of context are ignored, |
| 354 | and another scan is made. |
| 355 | .Pq The default maximum fuzz factor is 2. |
| 356 | .Pp |
| 357 | If |
| 358 | .Nm |
| 359 | cannot find a place to install that hunk of the patch, it will put the hunk |
| 360 | out to a reject file, which normally is the name of the output file plus |
| 361 | .Qq .rej . |
| 362 | (Note that the rejected hunk will come out in context diff form whether the |
| 363 | input patch was a context diff or a normal diff. |
| 364 | If the input was a normal diff, many of the contexts will simply be null.) |
| 365 | The line numbers on the hunks in the reject file may be different than |
| 366 | in the patch file: they reflect the approximate location patch thinks the |
| 367 | failed hunks belong in the new file rather than the old one. |
| 368 | .Pp |
| 369 | As each hunk is completed, you will be told whether the hunk succeeded or |
| 370 | failed, and which line (in the new file) |
| 371 | .Nm |
| 372 | thought the hunk should go on. |
| 373 | If this is different from the line number specified in the diff, |
| 374 | you will be told the offset. |
| 375 | A single large offset MAY be an indication that a hunk was installed in the |
| 376 | wrong place. |
| 377 | You will also be told if a fuzz factor was used to make the match, in which |
| 378 | case you should also be slightly suspicious. |
| 379 | .Ss Filename Determination |
| 380 | If no original file is specified on the command line, |
| 381 | .Nm |
| 382 | will try to figure out from the leading garbage what the name of the file |
| 383 | to edit is. |
| 384 | When checking a prospective file name, pathname components are stripped |
| 385 | as specified by the |
| 386 | .Fl p |
| 387 | option and the file's existence and writability are checked relative |
| 388 | to the current working directory (or the directory specified by the |
| 389 | .Fl d |
| 390 | option). |
| 391 | .Pp |
| 392 | If the diff is a context or unified diff, |
| 393 | .Nm |
| 394 | is able to determine the old and new file names from the diff header. |
| 395 | For context diffs, the |
| 396 | .Dq old |
| 397 | file is specified in the line beginning with |
| 398 | .Qq *** |
| 399 | and the |
| 400 | .Dq new |
| 401 | file is specified in the line beginning with |
| 402 | .Qq --- . |
| 403 | For a unified diff, the |
| 404 | .Dq old |
| 405 | file is specified in the line beginning with |
| 406 | .Qq --- |
| 407 | and the |
| 408 | .Dq new |
| 409 | file is specified in the line beginning with |
| 410 | .Qq +++ . |
| 411 | If there is an |
| 412 | .Qq Index: |
| 413 | line in the leading garbage (regardless of the diff type), |
| 414 | .Nm |
| 415 | will use the file name from that line as the |
| 416 | .Dq index |
| 417 | file. |
| 418 | .Pp |
| 419 | .Nm |
| 420 | will choose the file name by performing the following steps, with the first |
| 421 | match used: |
| 422 | .Bl -enum |
| 423 | .It |
| 424 | If |
| 425 | .Nm |
| 426 | is operating in strict |
| 427 | .St -p1003.2 |
| 428 | mode, the first of the |
| 429 | .Dq old , |
| 430 | .Dq new |
| 431 | and |
| 432 | .Dq index |
| 433 | file names that exist is used. |
| 434 | Otherwise, |
| 435 | .Nm |
| 436 | will examine either the |
| 437 | .Dq old |
| 438 | and |
| 439 | .Dq new |
| 440 | file names or, for a non-context diff, the |
| 441 | .Dq index |
| 442 | file name, and choose the file name with the fewest path components, |
| 443 | the shortest basename, and the shortest total file name length (in that order). |
| 444 | .It |
| 445 | If no file exists, |
| 446 | .Nm |
| 447 | checks for the existence of the files in an SCCS or RCS directory |
| 448 | (using the appropriate prefix or suffix) using the criteria specified |
| 449 | above. |
| 450 | If found, |
| 451 | .Nm |
| 452 | will attempt to get or check out the file. |
| 453 | .It |
| 454 | If no suitable file was found to patch, the patch file is a context or |
| 455 | unified diff, and the old file was zero length, the new file name is |
| 456 | created and used. |
| 457 | .It |
| 458 | If the file name still cannot be determined, |
| 459 | .Nm |
| 460 | will prompt the user for the file name to use. |
| 461 | .El |
| 462 | .Pp |
| 463 | Additionally, if the leading garbage contains a |
| 464 | .Qq Prereq:\ \& |
| 465 | line, |
| 466 | .Nm |
| 467 | will take the first word from the prerequisites line (normally a version |
| 468 | number) and check the input file to see if that word can be found. |
| 469 | If not, |
| 470 | .Nm |
| 471 | will ask for confirmation before proceeding. |
| 472 | .Pp |
| 473 | The upshot of all this is that you should be able to say, while in a news |
| 474 | interface, the following: |
| 475 | .Pp |
| 476 | .Dl | patch -d /usr/src/local/blurfl |
| 477 | .Pp |
| 478 | and patch a file in the blurfl directory directly from the article containing |
| 479 | the patch. |
| 480 | .Ss Backup Files |
| 481 | By default, the patched version is put in place of the original, with |
| 482 | the original file backed up to the same name with the extension |
| 483 | .Qq .orig , |
| 484 | or as specified by the |
| 485 | .Fl B , |
| 486 | .Fl V , |
| 487 | or |
| 488 | .Fl z |
| 489 | options. |
| 490 | The extension used for making backup files may also be specified in the |
| 491 | .Ev SIMPLE_BACKUP_SUFFIX |
| 492 | environment variable, which is overridden by the options above. |
| 493 | .Pp |
| 494 | If the backup file is a symbolic or hard link to the original file, |
| 495 | .Nm |
| 496 | creates a new backup file name by changing the first lowercase letter |
| 497 | in the last component of the file's name into uppercase. |
| 498 | If there are no more lowercase letters in the name, |
| 499 | it removes the first character from the name. |
| 500 | It repeats this process until it comes up with a |
| 501 | backup file that does not already exist or is not linked to the original file. |
| 502 | .Pp |
| 503 | You may also specify where you want the output to go with the |
| 504 | .Fl o |
| 505 | option; if that file already exists, it is backed up first. |
| 506 | .Ss Notes For Patch Senders |
| 507 | There are several things you should bear in mind if you are going to |
| 508 | be sending out patches: |
| 509 | .Pp |
| 510 | First, you can save people a lot of grief by keeping a |
| 511 | .Pa patchlevel.h |
| 512 | file which is patched to increment the patch level as the first diff in the |
| 513 | patch file you send out. |
| 514 | If you put a |
| 515 | .Qq Prereq: |
| 516 | line in with the patch, it won't let them apply |
| 517 | patches out of order without some warning. |
| 518 | .Pp |
| 519 | Second, make sure you've specified the file names right, either in a |
| 520 | context diff header, or with an |
| 521 | .Qq Index: |
| 522 | line. |
| 523 | If you are patching something in a subdirectory, be sure to tell the patch |
| 524 | user to specify a |
| 525 | .Fl p |
| 526 | option as needed. |
| 527 | .Pp |
| 528 | Third, you can create a file by sending out a diff that compares a |
| 529 | null file to the file you want to create. |
| 530 | This will only work if the file you want to create doesn't exist already in |
| 531 | the target directory. |
| 532 | .Pp |
| 533 | Fourth, take care not to send out reversed patches, since it makes people wonder |
| 534 | whether they already applied the patch. |
| 535 | .Pp |
| 536 | Fifth, while you may be able to get away with putting 582 diff listings into |
| 537 | one file, it is probably wiser to group related patches into separate files in |
| 538 | case something goes haywire. |
| 539 | .Sh ENVIRONMENT |
| 540 | .Bl -tag -width "PATCH_VERSION_CONTROL" -compact |
| 541 | .It Ev POSIXLY_CORRECT |
| 542 | When set, |
| 543 | .Nm |
| 544 | behaves as if the |
| 545 | .Fl Fl posix |
| 546 | option has been specified. |
| 547 | .It Ev SIMPLE_BACKUP_SUFFIX |
| 548 | Extension to use for backup file names instead of |
| 549 | .Qq .orig . |
| 550 | .It Ev TMPDIR |
| 551 | Directory to put temporary files in; default is |
| 552 | .Pa /tmp . |
| 553 | .It Ev PATCH_VERSION_CONTROL |
| 554 | Selects when numbered backup files are made. |
| 555 | .It Ev VERSION_CONTROL |
| 556 | Same as |
| 557 | .Ev PATCH_VERSION_CONTROL . |
| 558 | .El |
| 559 | .Sh FILES |
| 560 | .Bl -tag -width "$TMPDIR/patch*" -compact |
| 561 | .It Pa $TMPDIR/patch* |
| 562 | .Nm |
| 563 | temporary files |
| 564 | .It Pa /dev/tty |
| 565 | used to read input when |
| 566 | .Nm |
| 567 | prompts the user |
| 568 | .El |
| 569 | .Sh DIAGNOSTICS |
| 570 | Too many to list here, but generally indicative that |
| 571 | .Nm |
| 572 | couldn't parse your patch file. |
| 573 | .Pp |
| 574 | The message |
| 575 | .Qq Hmm... |
| 576 | indicates that there is unprocessed text in the patch file and that |
| 577 | .Nm |
| 578 | is attempting to intuit whether there is a patch in that text and, if so, |
| 579 | what kind of patch it is. |
| 580 | .Pp |
| 581 | The |
| 582 | .Nm |
| 583 | utility exits with one of the following values: |
| 584 | .Pp |
| 585 | .Bl -tag -width Ds -compact -offset indent |
| 586 | .It \&0 |
| 587 | Successful completion. |
| 588 | .It \&1 |
| 589 | One or more lines were written to a reject file. |
| 590 | .It \*[Gt]\&1 |
| 591 | An error occurred. |
| 592 | .El |
| 593 | .Pp |
| 594 | When applying a set of patches in a loop it behooves you to check this |
| 595 | exit status so you don't apply a later patch to a partially patched file. |
| 596 | .Sh SEE ALSO |
| 597 | .Xr diff 1 |
| 598 | .Sh AUTHORS |
| 599 | .An Larry Wall |
| 600 | with many other contributors. |
| 601 | .Sh CAVEATS |
| 602 | .Nm |
| 603 | cannot tell if the line numbers are off in an ed script, and can only detect |
| 604 | bad line numbers in a normal diff when it finds a |
| 605 | .Qq change |
| 606 | or a |
| 607 | .Qq delete |
| 608 | command. |
| 609 | A context diff using fuzz factor 3 may have the same problem. |
| 610 | Until a suitable interactive interface is added, you should probably do |
| 611 | a context diff in these cases to see if the changes made sense. |
| 612 | Of course, compiling without errors is a pretty good indication that the patch |
| 613 | worked, but not always. |
| 614 | .Pp |
| 615 | .Nm |
| 616 | usually produces the correct results, even when it has to do a lot of |
| 617 | guessing. |
| 618 | However, the results are guaranteed to be correct only when the patch is |
| 619 | applied to exactly the same version of the file that the patch was |
| 620 | generated from. |
| 621 | .Sh BUGS |
| 622 | Could be smarter about partial matches, excessively deviant offsets and |
| 623 | swapped code, but that would take an extra pass. |
| 624 | .Pp |
| 625 | Check patch mode |
| 626 | .Pq Fl C |
| 627 | will fail if you try to check several patches in succession that build on |
| 628 | each other. |
| 629 | The entire |
| 630 | .Nm |
| 631 | code would have to be restructured to keep temporary files around so that it |
| 632 | can handle this situation. |
| 633 | .Pp |
| 634 | If code has been duplicated (for instance with #ifdef OLDCODE ... #else ... |
| 635 | #endif), |
| 636 | .Nm |
| 637 | is incapable of patching both versions, and, if it works at all, will likely |
| 638 | patch the wrong one, and tell you that it succeeded to boot. |
| 639 | .Pp |
| 640 | If you apply a patch you've already applied, |
| 641 | .Nm |
| 642 | will think it is a reversed patch, and offer to un-apply the patch. |
| 643 | This could be construed as a feature. |