| blob | fc22772f77aab6f7acd8d0281373f9f6c80c5e42 |
1 p is a tool for managing patches. It contains many
2 subcommands. To use a particular subcommand, give it
3 as the first argument to p, and then give any arguments
4 that subcommand requires
6 files
7 p keeps all it's files and patches in a subdirectory of
8 the toplevel directory of a project. This subdirectory
9 is called ".patches". It is often convenient for
10 ".patches" to actually be a symbolic link to somewhere
11 else altogether.
13 The files and directories contained in .patches are:
14 applied/ A directory containing applied patches
15 removed/ A directory containing removed patches
16 include/ A directory containing included patches
17 Files in these directories are prefixed by a 3digit number
18 which indicate thr order in which patches were added.
19 The remainder of the filename is the name of the patch.
20 Each file contains:
21 Status: status
22 ... notes ...
23 ... diffstat output ...
24 the actual patch
25 name A file containing the name of the current patch
26 status A file containing the status of the current patch
27 notes A file with notes about the patch
28 patch A a recently generated copy of the current patch
29 files A list of files that are 'checked out'
30 to-resolve A list of files that might have conflicts that need resolving
31 tmp A temporary file
32 last-applied A most recently apply patch that had conflicts
33 last-purge
34 dest/ A directory where 'p publish' puts patch sets.
35 SOURCE/ A directory where a bk repository lives.
36 mail/ A directory of patches converted to email messages
37 cc A files listing: prefix name emailaddr
38 When mailing patches which start with prefix, name
39 is put on the subject line, and the mail is cc:ed to
40 emailaddr
41 maintainer This is where patches are mailed to
42 owner These mail headers are included in each mail message
43 get-version A script to get a base version number for use when publishing
44 to-resolve List of files have have outstanding conflicts to be resolved.
47 model
48 overview
49 What is 'p' ?
51 'p' is a patch management system, not a source code control system.
52 It allows you to create a set of patches against a base release, to
53 annotate those patches with comments, and to revisit and edit patches
54 after they have been committed.
56 It also allows you to update the base release that the patches are
57 against, and then re-apply all patches.
59 At any time, there are a number of applied patches, a number of
60 removed patches and possibly a current patch.
61 The sets of applied and removed patches act much like stacks. The current
62 patch can be moved to the top of either (commit or discard), and the top
63 of either patch can be moved to the current patch (open or apply).
64 open and apply actualy allow any patch in the corresponding stack to be
65 made current, and assume that the use won't re-order patches that
66 should not be re-ordered.
68 To enable 'p' for a project, you simply create a directory called ".patches"
69 in the top level directory of that project. Files should be checked out
70 ("p co filename") before editing but never need to be checked in. Applying
71 and external patch automatically checks out all modified files.
73 Often it is appropriate to have the .patches directory elsewhere (for
74 example in an http-export directory tree for public access) and have a
75 symlink from .patches to that location.
77 p can be run from any subdirectory of a project containing a .patches
78 directory.
80 To find out about the contents of the .patches directory, see
81 p help files
83 Some common commands are:
84 p co filename # monitor changes to filename
85 p make # create and view the current patch
86 p commit # commit the current patch
87 p discard # discard current patch, saving it as
88 # a removed patch
89 p apply # re-apply a removed patch, or apply
90 # an external patch
91 p list # list current patches
93 co
94 Usage: p co filename
96 prepare filename for editing. This makes sure there is a
97 copy of the file with a ~current~ suffix, and that the file
98 is listed in in .patches/files. This command can be run from
99 a subdirectory of the project, and it will still do the
100 right thing.
102 make
103 view
104 Usage: p make
105 p view [patchnamefragment]
107 make and view provide the same functionality.
108 When given a patch name fragment, they will allow the unique
109 patch with that name (either applied or removed) to be viewed
110 (using the pager $PAGER, or less).
111 Without an argument, the current patch is calculated and
112 displayed. This explains the two names as with no argument,
113 they both make, and view the current patch.
115 all
116 Usage: p all
118 Generate a composite patch of all currently applied patches.
119 This involves creation a patch from the ~orig~ version of every
120 file to it's current version.
122 status
123 name
125 Usage: p status [newstatus]
126 p name [newname]
128 If a new status or name is given, it is recorded as the current
129 status or name for the current patch. If no argument is given,
130 the command will prompt for both a new name and a new status.
131 The current value is offered as a default in each case.
133 note
134 notes
135 Usage: p notes
137 Open the notes describing the current patch in an $EDITOR
138 The notes should contain a simple one-line description,
139 a black line, and then a detailed description.
141 discard
142 Usage: p discard
144 The current patch is discard: moved to the .patches/removed
145 directory. If it doesn't have a name or status, these are
146 prompted for.
148 commit
149 Usage: p commit
151 The current patch is commit: moved to the .patches/applied
152 directory. If name or status aren't set, these are prompted
153 for. If no notes have been written, and $EDITOR session is
154 started with a template for some notes.
155 The patch is presented in the file being edited for reference,
156 but will be removed from the notes on exit.
158 open
159 Usage: p open [last | patch-name-fragment]
161 The open command is used to open a previously commited
162 patch for further editing.
164 Without any argument, a list of available commited patches
165 is given.
166 If the argument 'last'is given, then the most recently commited
167 patch is opened.
168 Otherwise a unique patch with a name containing the name fragment
169 is openned. If there is no such unique patch, and error message
170 is given.
172 included
173 Usage: p included [-f] [last | patch-name-fragment]
175 After updating the base release of a project, some of the patches
176 which are currently "removed" may already have been included in that
177 release and so don't need to be maintained any more.
179 The "included" command will check if a given patch appears to have
180 been included and if so, moves it to the .patches/included directory.
181 The test is performed by seeing if 'patch' is able to remove the
182 patch. If it cannot, but you are sure that the patch has been included
183 (the problems patch reports are spurious) then using '-f' will cause
184 the patch to be moved to 'included' anyway.
186 list
187 Usage: p list
189 List all the patches in either 'applied' or 'removed'.
191 apply
192 Usage: p apply [-f] [-a] [last | patch-name-fragment | filename]
194 This command is used for applying a patch to the project.
195 If a patch in 'removed' is given, then it is moved out of 'removed'
196 and is applied. If a filename is given, the patch in that file is
197 applied but the file is left unchanged.
199 When applying a patch, all affected files are checked-out first.
201 If 'patch' cannot apply the patch without error, 'apply' will fail.
202 Giving the '-f' option will cause 'apply' to apply the patch anyway,
203 and then run 'wiggle' to merge any rejected patch chunks as best
204 as possible. Any files for which wiggle finds unresolvaable conflicts
205 while have its name saved in a file (.patches/to-resolve). This
206 list is used by the 'p resolve' command.
208 Normally, 'apply' will not apply a patch to be applies if there is
209 one already open. However the '-a' option may be given to ask
210 'apply' to "append" the patch to the current patch.
212 resolve
213 Usage: p resolve
215 This is used to resolve any conflicts found by wiggle. Each file
216 listed in .patches/to-resolve is presented for editing, and then
217 has wiggle run over it again to check that all conflicts have
218 been resolved.
220 publish
221 Usage: p publish
223 The 'publish' command will create a new subdirectory of
224 .patches/dest
225 (which is often a symlink to a web-page area) and copy
226 all current applied and removed patches into that directory.
227 It also creates a complete patch (with "p all") and stores
228 that in the directory.
230 clean
231 Usage: p clean
233 clean checks that no patches are currently applied, and
234 cleans up any ~current~ or ~orig~ files that have been left
235 in the source tree. It also removed write permission from
236 all checked-out files.
238 It effectively undoes all check-outs.
240 It is run as part of 'update' which incorporates upstream
241 changes into a source tree.
243 openall
244 Usage: p openall
246 This command repeatedly runs "p open last && p discard" until
247 that fails, which usually means that all patches have been
248 discarded. This is part of the preparation for incorporating
249 upstream changes.
251 snapshot
252 Usage: p snapshot
254 This command takes a shapshot of the current patch so that further
255 work can be done in the patch, but it can easily be removed if
256 there are problems.
258 This might be used before appending a patch incase something goes
259 wrong in the appending process.
261 snapdiff
262 Usage: p snapdiff
264 Display the differences between the latest snapshot and the current
265 source.
267 snapback
268 Usage: p snapback
270 Revert all changes since the last snapshot
272 pull
273 Usage: p pull
275 Update the local copy of the official source repository. This
276 can be found by following the .patches/SOURCE link.
278 Currently the code assumes it is a BitKeeper repository and
279 runs "bk pull". It should be enhanced to recognise CVS and
280 run "cvs update".
282 update
283 Usage: p update
285 This command updates the based release of the package. To
286 do this it removes all patches (p openall), cleans up (p clean),
287 creates a patch from information in .patches/SOURCE, and applies
288 that patch. It currently makes no attempt to re-apply any
289 patches, or to "p included" and patches.
291 Currently the code assumes a BitKeeper repository and uses
292 "bk export -tpatch -rLASTEST," to extract a patch, and then
293 retags the repository with "bk tag LATEST". It should be
294 enhanced to recognise and work with CVS as well.
296 premail
297 Usage: p premail [patch-name-prefix]
299 This command converts a selection of patches to Email messages.
300 The email messages are stored in .patches/mail.
301 SAY MORE HERE
303 nomail
304 Usage: p nomail
306 Remove the .patches/mail directory and contents.
308 email
309 Usage: p email
311 Send all mail messages in .patches/mail. On success, each
312 email message is removed.
314 help
315 Usage: p help [topic]
317 Print out help messages, which are contained in a file
318 p.help
319 in the same directory that p was run from.
320 Without a topic, a general introduction and a list of topics
321 is presented. With a topic, help on that topic is presented.
323 purge
324 Usage: p purge
326 Make copy of the current patch in .patches/last-purge (just
327 in case) and then purge the current patch complete.