rpmdev-patchbuild.1

.TH RPMDEV-PATCHBUILD "1" "Last change: $Format:%ci$" "rpmdev-pathcbuild $Format:%h$" "User Commands"
.SH NAME
rpmdev-patchbuild - synchronize patch set between spec and source
.SH SYNOPSIS
.B rpmdev-patchbuild [\fIoptions\fR] <\fIcommand\fR> [\fIspec file\fR]
.SH DESCRIPTION
\fIrpmdev-patchbuild\fR is designed to support the workflow when
maintaining patches in RPM spec files. It can export existing
patches to a build tree. This build tree can be modified with new
or updated patches. Eventually, the patches in the spec file can
be updated (i. e., replaced) with the patches in the build tree.
.SH ARGUMENTS
The \fBcommand\fR argument is one of
.RS 4
.TP
\fIexport\fR
Retrieves the sources as defined in the spec file and unpacks them into
a build tree. The patches in the spec are applied as a patch series in this
tree.
.TP
\fIimport\fR
Import the patches from the build tree. The patches in the spec file are
replaced with the patches from build tree.
.TP
\fIstatus\fR
Display the patch status. A patch can be deleted, new, modified or
unchanged. A new patch might conflict if using a numeric prefix used
by another patch
.TP
\fIreset\fR
Reset the patch numbering (git mode only). Removes existing patches and
replaces them with a new set generated by \fIgit format-patch\fR.
.TP
\fIversion\fR
Print version
.RE
.TP
\fBspec file\fR
The spec file to use. Defaults to \fI*.spec\fR (which must match a single
file to work).

.SH OPTIONS
.TP
\fB\-m\fR ,\fB\-\-mode\fR [\fIgit\fR|\fIquilt\fR|\fIautosetup\fR]
Work either in  git,  quilt or autosetup mode. See QUILT MODE, GIT MODE,
and AUTOSETUP MODE. Modes can be abridged to the initial letters \fIg\fR,
\fIq\fR and \fIa\fR. This setting is sticky - the value used in the
\fIexport\fR command is the default used in other commands.
.TP
\fB-o\fR,\fB\-\-options\fR
Options used with  \fI%patch\fR when importing new patches. Defaults to
\fI-p2\fR in \fIquilt\fR mode, otherwise \fI-p1\fR. Existing \fI%patch\fR
invocations are used as-is.  The option is sticky in same way as the
\fImode\fR option.
.TP
\fB-w\fR,\fB\-\-working-dir\fR
Build directory where sources are unpacked. Defaults to \fIpatchbuild\fr.
.TP
\fB\-h\fR,\fB\-\-help\fR
Display usage summary.
.TP
\fB\-v\fR,\fB\-\-version\fR
Display version.

.SH QUILT MODE
In quilt mode the build tree is initiated with a \fIquilt(1)\fR
patchset. This mode can always be used for "normal" spec files
using %patch to apply the patches. It does not parse or generate
any patch metadata. It also leaves patch naming including numbering
to the user. After a \fIquilt refresh\fR command the patchset is
updated and visible for \fNrpmdev-patchbuild\fR. Quilt mode is
used by default if at least one patch is deemed as non-git.

.SH GIT  MODE
.P
In git mode the build tree is initiated with a \fIgit(1)\fR
repository, and each patch in the spec will be applied using
\fIgit am\fR. Requires that all spec patches are git-formatted.
This mode is used by default if all patches in the spec are deemed
as git patches according to some heuristics.
.P
\fBrpmdev-patchbuild\fR does not import the git repo directly, it
uses the \fIpatchbuild/patches\fR directory. One way to feed it
is to just invoke something like \fIgit format-patch \-\-start-number 7
 \-o ../patches HEAD^..HEAD\fR. This gives user fine-grained control over
the patches imported. The alternative is to use the \fIreset\fR command
which generates a fresh, re-numbered patchset in ../patches.
.P
In git mode all changes done by %prep besides the actual patching is
discarded by \fIexport\fR.

.SH AUTOSETUP MODE
In the autosetup mode \fBrpmdev-patchbuild\fR assumes that the  spec file
doesn't use \fI%patch\fR macros for applying the patches. No modifications
are done to the %prep section in the spec file, only the \fIPatch:\fR tag
lines are parsed and modified. Likewise, no modifications are done to the
spec when it is used to unpack the sources in the \fIexport\fR command.
.P
Like in the git mode, only the patches/ directory is consulted for the actual
patchset. This means that \fBrpmdev-patchbuild\fR is agnostic as to how this
is created. A common way would be the \fIgit format-patch\fR described for
the git mode.

.SH SPEC FILE MODIFICATIONS
Updating an existing patch does not affect the spec file, only the contents
of the patch file.
.P
When deleting a patch the corresponding entry in the spec is commented
out.
.P
When inserting a new patch, the \fIPatch:\fR tag line and the \fI%patch\fR
is inserted ordered to existing lines. If there is no existing patch the
tag line is inserted after the last Source: and the patch line after %setup.
.P
Both deleted and inserted patches creates fixes which looks ugly and needs
some manual editing before committing.
.P
When imported a new patch must be designated a number. If the patch
filename doesnt have a numeric prefix the next available number is
used. It the patch has a numeric prefix it will be used unless it's
already used in the spec. In this case there is a warning and next
available number is used.

.SH EXAMPLES
A session using \fBrpmdev-patchbuild\fR might look like:
.nf
    $ fedpkg clone foo
    $ cd foo
    $ rpmdev-patchbuild export
    $ cd patchbuild/foo-1.0.3
    < patch the code and update patches>
    $ cd ../..
    $ rpmdev-patchbuild status
    $ rpmdev-patchbuild import
    $ rpmbuild -D "_sourcedir $PWD" -ba *.spec
    < patch broken... fix in patchbuild/foo-1.0.3>
    $ rpmdev-patchbuild import
    $ rpmbuild -D "_sourcedir $PWD" -ba *.spec
    <all OK, commit changes in main git repo>
    $ git commit -am "foo fixed with new patches"
.fi

.SH BUGS

When unpacking the build dependencies are not used. In corner cases where the
%prep section uses tools from the builddeps the export command will fail.
Installing the build dependencies for the spec file should fix it.
.P
If a specfile unpacks two or more separate directories in the top level
\fBrpmdev-patchbuild\fR gets confused.

.SH SEE ALSO

quilt(1)
.br
git(1)
.br