harvey/sys/man/1/patch

.TH PATCH 1
.SH NAME
patch \- simple patch creation and tracking system
.SH SYNOPSIS
.B patch/create
[
.B -f
]
.I name
.I email
.I files ...
[
.B < 
.I description
]
.PP
.B patch/list
[
.B -av
]
[
.I name ...
]
.PP
.B patch/pull
.PP
.B patch/pullbin
.PP
.B patch/diff
.I name
.PP
.B patch/apply
.I name
.PP
.B patch/Apply
.I name
.PP
.B patch/undo
.I name
.PP
.B patch/applied
.I name 
.PP
.B patch/notify
.SH DESCRIPTION
These scripts are a simple patch submission and tracking system
used to propose additions or changes to Nix. They are similar to Plan 9
.IR patch (1)
tools but there are important differences.
.PP
Each patch has a 
.I name
(lowercase letters, numbers, dash, dot, and underscore only)
and is stored in
.BI /n/patches.lsub.org/patch/ name.
.PP
Users are expected to use only
.I patch/create
to create patches and
.I patch/pull
to pull (apply) new patches that have been applied to the main distribution.
All other tools are for contributors and maintainers.
.PP
.I Patch/pull
applies to the tree mounted at
.I /n/dist
all patches applied to the main nix tree but not yet applied
to that tree. 
If there is no tree mounted at
.I /n/dist
then
.I patch/pull
will bind
.B /
there, and apply patches to the tree you are using.
The history of patches applied to a tree is always kept at
.B /dist/patch/applied
within that tree.
.PP
To use this tool it is important that
.I patch/applied
is either not used (from outside this tool) or is used to apply
the patches in exactly the same order used by the main tree.
.PP
.I Patch/pullbin
relies on
.IR up (1)
to suggest commands to update
.B /386/bin
and
.B /386/lib
with those found in the distribution.
No remove command will be issued if a binary is
removed from the distribution, and newer local binaries
will be left alone.
.PP
.I Patch/create
creates a new patch (or redefines an existing one) consisting of the changes to
the listed files from the distribution, reading
a description of the patch from standard input:
please provide an explanation of what the change is supposed to do,
some context, and a rationale for the change.
Test data or pointers to same to verify that the fix works are also welcome.
When sending a patch, follow these guidelines:
.IP • 3
Before preparing the patch, run
.I patch/pull
and base your patch on current distribution source code.
.IP •
If this is a bug fix, explain the bug clearly.
Don't assume the bug is obvious from the fix.
.IP •
If this is a new feature, explain it clearly.
Don't assume it is obvious from the change.
.IP •
Make the new code look as much like the old code as possible:
don't make gratuitous changes, and do follow the style of the old code.
See
.IR style (6)
for the canonical Plan 9 coding style, used in Nix.
.IP •
If your patch changes externally-visible behaviour,
update the manual page.
.PP
The
.I email
address, if not
.LR - ,
will be included in the mail to notify that the patch has been created. All
patch discussion will proceed in the same mail thread, until the patch
is accepted or rejected. If it is rejected, the usual course of action is to
create
a new patch using the same name, after having addressed the comments
discussed by mail.
.PP
When you run
.I patch/create
to create a patch, the tree you are using considers the patch as applied, so that
further
.I patch/pull
calls in that tree will not try to apply an already applied patch.
.PP
Running
.I patch/create
with the name of an existing patch can be used to modify a not yet
applied patch. In this case, flag
.B -f
must be supplied or the tool will refuse to continue, to prevent accidental
redefinition of existing patches.
.PP
.I Patch/list
displays information about the named patches,
or all currently pending patches if none are specified. Under flag
.B -a
it list all existing patches.
Flag
.B -v
makes the tool verbose.
.PP
.I Patch/diff
shows a patch as diffs between the original
source files and the patched source files.
.PP
.I Patch/apply
applies the patch to the current source tree mounted on
.B /n/dist
(the current tree if none is mounted there).
If the source has changed since the patch was
created,
.I apply
will report the conflict and not change any files.
Before changing any files,
.I patch/apply
makes backup copies of the current source tree's
files.  The backups are stored in the patch directory created at
.B /dist/patch
for processing the patch.
.PP
After applying a patch, one of
.I patch/undo
and
.I patch/applied
must be executed:
.I Patch/undo
will copy the backups saved by
.I patch/apply
back into the source tree.
.I Patch/applied
records the patch as applied.
.PP
.I Patch/Apply
is used by the main tree maintainers to apply patches to it.
It is exactly
.I patch/apply
with a few changes to operate on the main Nix tree.
.PP
.I Patch/notify
is run frequently close to the main distribution to notify by mail of patch creations.
.PP
If there are conflicts you can resolve them by manually updating your local files
as you please and then running
.IR patch/appied ,
which declares the patch as applied. To update your local files you can refer to the
.BI /dist/patch/ patchname 
directory which keeps the list of files affected as well as their old and new versions.
.SH EXAMPLES
Propose a change to
.IR pwd ,
which you have modified locally:
.IP
.EX
% patch/create pwd-errors user@host.dom /sys/src/cmd/pwd.c
Fix pwd to print errors to fd 2 rather than 1.
^D
% 
.EE
.PP
Then the distribution maintainers and patch reviewers run
.IP
.EX
patch/diff pwd-errors
.EE
.PP
to inspect the change (possibly viewing
.B /n/patches.lsub.org/patch/pwd-errors/pwd.c
to see the larger context).
To try the change, they run
.IP
.EX
patch/apply pwd-errors
.EE
.LP
After that, they run
.IP
.EX
% patch/undo pwd-errors
% 
.EE
.PP
to end the trial. Should the patch be accepted, maintainers run
.IP
.EX
patch/Apply pwd-errors
.EE
.PP
to apply it to the main distribution. After that, those that run
.IP
.EX
patch/pull
.EE
.PP
will get the new patch (as well as any other ones applied to the
main distribution, but not yet locally applied).
.PP
To ignore a patch and skip it from pull you can
.EX
echo patchname >>/dist/patch/applied
.EE
.SH FILES
.B /n/patches.lsub.org/patch
.B /n/sources.lsub.org/nix
.B /dist/patch
.SH SOURCE
.B /rc/bin/patch
.SH SEE ALSO
.IR diff (1)