sys/man/1/patch

   1 .TH PATCH 1
   2 .SH NAME
   3 patch \- simple patch creation and tracking system
   4 .SH SYNOPSIS
   5 .B patch/create
   6 .I name
   7 .I email
   8 .I files ...
   9 [
  10 .B <
  11 .I description
  12 ]
  13 .PP
  14 .B patch/list
  15 [
  16 .I name ...
  17 ]
  18 .PP
  19 .B patch/diff
  20 .I name
  21 .PP
  22 .B patch/apply
  23 .I name
  24 .PP
  25 .B patch/undo
  26 .I name
  27 .PP
  28 .B patch/note
  29 .I name
  30 [
  31 .B <
  32 .I note
  33 ]
  34 .SH DESCRIPTION
  35 These scripts are a simple patch submission and tracking system
  36 used to propose additions or changes to Plan 9.
  37 There is no guarantee that any patch will be accepted, nor
  38 that it will be accepted verbatim.
  39 Each patch has a
  40 .I name
  41 (lowercase letters, numbers, dash, dot, and underscore only)
  42 and is stored in
  43 .BI /n/sources/patch/ name.
  44 .PP
  45 .I Patch/create
  46 creates a new patch consisting of the changes to
  47 the listed files from the distribution, reading
  48 a description of the patch from standard input:
  49 please provide an explanation of what the change is supposed to do,
  50 some context, and a rationale for the change.
  51 Test data or pointers to same to verify that the fix works are also welcome.
  52 When sending a patch, follow these guidelines:
  53 .IP • 3
  54 Before preparing the patch, run
  55 .I replica/pull
  56 and base your patch on current distribution source code.
  57 .IP •
  58 If this is a bug fix, explain the bug clearly.
  59 Don't assume the bug is obvious from the fix.
  60 .IP •
  61 If this is a new feature, explain it clearly.
  62 Don't assume it is obvious from the change.
  63 .IP •
  64 Make the new code look as much like the old code as possible:
  65 don't make gratuitous changes, and do follow the style of the old code.
  66 See
  67 .IR style (6)
  68 for the canonical Plan 9 coding style.
  69 .IP •
  70 If your patch changes externally-visible behaviour,
  71 update the manual page.
  72 .PP
  73 The
  74 .I email
  75 address, if not
  76 .LR - ,
  77 will be sent notification messages when the patch is applied, rejected,
  78 or commented on.
  79 If rejected, the e-mail will contain a note explaining why and
  80 probably listing suggested changes and encouraging you to resubmit.
  81 .PP
  82 .I Patch/list
  83 displays information about the named patches,
  84 or all currently pending patches if none are specified.
  85 .PP
  86 .I Patch/diff
  87 shows a patch as diffs between the original
  88 source files and the patched source files.
  89 .PP
  90 .I Patch/apply
  91 applies the patch to the current source tree.
  92 It is intended to be run by the Plan 9 developers with
  93 .B pie
  94 as their root file system.
  95 If the source has changed since the patch was
  96 created,
  97 .I apply
  98 will report the conflict and not change any files.
  99 Before changing any files,
 100 .I patch/apply
 101 makes backup copies of the current source tree's
 102 files.  The backups are stored in the patch directory.
 103 .PP
 104 .I Patch/undo
 105 will copy the backups saved by
 106 .I patch/apply
 107 back into the source tree.
 108 It will not restore a backup if the file
 109 being replaced is not byte-identical to the one
 110 created by
 111 .I patch/apply.
 112 .SH EXAMPLES
 113 Propose a change to
 114 .IR pwd ,
 115 which you have modified locally:
 116 .IP
 117 .EX
 118 % patch/create pwd-errors user@host.dom /sys/src/cmd/pwd.c
 119 Fix pwd to print errors to fd 2 rather than 1.
 120 ^D
 121 %
 122 .EE
 123 .PP
 124 Then the developers at Bell Labs run
 125 .IP
 126 .EX
 127 patch/diff pwd-errors
 128 .EE
 129 .PP
 130 to inspect the change (possibly viewing
 131 .B /n/sources/patch/pwd-errors/pwd.c
 132 to see the larger context).
 133 To make the change, they run
 134 .IP
 135 .EX
 136 patch/apply pwd-errors
 137 .EE
 138 .LP
 139 Otherwise they run
 140 .IP
 141 .EX
 142 % patch/note pwd-errors
 143 Pwd should definitely print errors to fd 1 because ...
 144 ^D
 145 %
 146 .EE
 147 .PP
 148 to add a note to the
 149 .B /n/sources/pwd-errors/notes
 150 file.
 151 .SH FILES
 152 .B /n/sources/patch
 153 .SH SOURCE
 154 .B /rc/bin/patch
 155 .SH SEE ALSO
 156 .IR diff (1)
 157 .br
 158 .B http://plan9.bell-labs.com/wiki/plan9/How_to_contribute