main.tex

linux下各种patch的管理工具

themselves are all that's needed. The \textsl{.pc} directory only
contains quilt's working state, and should not be distributed. Make sure
that all the patches are up-to-date, and refresh patches when
necessary. The \textsf{--combine} option of \quilt{diff} can be used for
generating a single patch out of all the patches in the series file.

\subsection{Merging with upstream}

The concept of merging your patches with upstream is identical to applying
your patches on a more recent version of the software. 

Before merging, make sure to pop all your patches using \quilt{pop -a}.
Then, update your codebase. Finally, remove obsoleted patches
from the series file and \quilt{push} the remaining ones, resolve
conflicts and refresh patches as needed.

\subsection{Forking}
\label{sec:forking}

There are situations in which updating a patch in-place is not ideal:
the same patch may be used in more than one series file. It may also
serve as convenient documentation to retain old versions of patches, and
create new ones under different names. This can be done by hand by
creating a copy of a patch (which must not be applied), and updating the
patch name in the series file.

The \quilt{fork} command simplifies this: it creates a copy of the
topmost patch in the series, and updates the series file. Unless a patch
name is explicitly specified, \quilt{fork} will generate the following
sequence of patch names: \textsf{patch.diff}, \textsf{patch-2.diff},
\textsf{patch-3.diff},\dots

\subsection{Dependencies}
\label{sec:dependencies}

When the number of patches in a project grows large, it becomes
increasingly difficult to find the right place for adding a new patch in
the patch series. At a certain point, patches will get inserted at the
end of the patch series, because finding the right place has become too
complicated. In the long run, a mess accumulates.

To help avoid this by keeping the big picture, the \quilt{graph} command
generates \textit{dot} graphs showing the dependencies between
patches.\footnote{
	The \quilt{graph} command computes dependencies based on
	which patches modify which files, and optionally will also
	check for overlapping changes in the files. While the former
	approach will often result in false positives, the latter
	approach may result in false negatives (that is, \quilt{graph}
	may overlook dependencies).
} The ouput of this command can be visualized using the tools from AT\&T
Research's Graph Visualization Project (GraphViz,
\url{http://www.graphviz.org/}).  The \quilt{graph} command supports
different kinds of graphs.

\subsection{Advanced Diffing}

Quilt allows us to diff and refresh patches that are applied, but are not
on top of the stack (\quilt{diff -P \textit{patch}} and \quilt{refresh
\textit{patch}}). This is useful in several cases, for example, when
%\begin{itemize}
%
%\item When the topmost patch has been modified but the changes are not
%yet completed, refreshing the patch would leave a patch file that is in
%an inconsistent state. Without that, the patch cannot be removed from
%the stack, or else the changes would be lost.
%
%\item Popping patches and then pushing them again results in modified
%time stamps. This may trigger time consuming recompiles.
%
%\item It is simply convenient to be able to fix small bugs in patches
%further down in the stack without much ado.
%
%\end{itemize}
%
patches applied higher on the stack modify some of the files that this
patch modifies. We can picture this as a shadow which the patches higher
on the stack throw on the files they modify.  When refreshing a patch,
changes to files that are not shadowed (and thus were last modified by
the patch that is being refreshed) are taken into account. The
modifications that the patch contains for shadowed files will not be
updated.

The \quilt{diff} command allows us to merge multiple patches into one by
optionally specifying the range of patches to include (see \quilt{diff
-h}). The combined patch will only modify each file contained in these
patches once. The result of applying the combined patch is the same as
applying all the patches in the specified range in sequence.

Sometimes it is convenient to use a tool other than \prog{GNU diff} for
comparing files (for example, a graphical diff replacement like
\prog{tkdiff}). Quilt will not use tools other than \prog{GNU diff} when
updating patches (\quilt{refresh}), but \quilt{diff} can be passed the
\textsf{-{}-diff=\textit{utility}} argument. With this argument, the
specified utility is invoked for each file that is being modified with
the original file and new file as arguments. For new files, the first
argument will be \textsf{/dev/null}.  For removed files, the second
argument will be \textsf{/dev/null}.

When \quilt{diff} is passed a list of file names, the diff will be
limited to those files. With the \textsf{-R} parameter, the original and
new files are swapped, which results in a reverse diff.

Sometimes it is useful to create a diff between an arbitrary state of
the working tree and the current version. This can be used to create a
diff between different versions of a patch (see
Section~\ref{sec:forking}), etc. To this end, quilt allows us to take a
snapshot of the working directory (\quilt{snapshot}). Later, a diff
against this state of the working tree can be created with \quilt{diff
-{}-snapshot}.

Currently, only a single snapshot is supported. It is stored in the
\textsf{.pc/.snap} directory.  To recover the disk space the snapshot
occupies, it can be removed with \quilt{snapshot -d}, or by removing the
\textsf{.pc/.snap} directory manually.

\subsection{Working with RPM Packages}
\label{sec:rpm}

Several Linux distributions are based on the RPM Package
Manager~\cite{max-rpm}. RPM packages consist of a spec that defines how
packages are built, and a number of additional files like tar archives,
patches, etc.  Most RPM packages contain an official software package
plus a number of patches. Before these patches can be manipulated with
quilt, a series file must be created that lists the patches along with
their strip levels.

The \quilt{setup} command automates this for most RPM packages. When
given a spec file as its argument, it performs the \textsf{\%prep}
section of the spec file, which is supposed to extract the official
software package, and apply the patches. In this run, quilt remembers
the tar archives and the patches that are applied, and creates a series
file.  Based on that series file, \quilt{setup} extracts the archives,
and copies the patches into the \textsf{patches} sub-directory. Some
meta-information like the archive names are stored as comments in the
series file. \quilt{setup} also accepts a series file as argument (which
must contain some meta-information), and sets up the working tree from
the series file in this case.

\section{Customizing Quilt}

Upon startup, quilt evaluates the file \textsf{.quiltrc} in the user's
home directory, or the file specified with the \textsf{--quiltrc} option.
This file is a regular bash script. Default options can be passed to
any command by defining a \textsf{QUILT\_\textit{COMMAND}\_ARGS} variable
(for example, \textsf{QUILT\_DIFF\_ARGS="--color=auto"} causes the output
of \quilt{diff} to be syntax colored when writing to a terminal).

In addition to that, quilt recognizes the following variables:

\begin{description}

\item[\textsf{QUILT\_DIFF\_OPTS}]
Additional options that quilt shall pass to \prog{GNU diff} when
generating patches. A useful setting for C source code is
``\textsf{-p}'', which causes \prog{GNU diff} to show in the resulting
patch which function a change is in.

\item[\textsf{QUILT\_PATCH\_OPTS}]
Additional options that quilt shall pass to \prog{GNU patch} when
applying patches. (For example, some versions of \prog{GNU patch}
support the ``\textsf{--unified-reject-files}'' option for generating
reject files in unified diff style.

\item[\textsf{QUILT\_PATCHES}]
The location of patch files (see Section~\ref{sec:basic}).  This setting
defaults to ``\textsf{patches}''.

\end{description}

\section{Pitfalls and Known Problems}

As mentioned earlier, files must be added to patches before they can be
modified. If this step is overlooked, one of the following problems will
occur: If the file is included in a patch further below on the stack,
the changes will appear in that patch when it is refreshed, and for that
patch the \quilt{pop} command will fail before it is refreshed.  If the
file is not included in any applied patch, the original file in the
working tree is modified.

Patch files may modify the same file more than once. \prog{GNU patch}
has a bug that corrupts backup files in this case. A fix is available,
and will be integrated in a later version of \textit{GNU patch}.  The fix has
already been integrated into the SUSE version of \textit{GNU patch}.

There are some packages that assume that it's a good idea to remove all
empty files throughout a working tree, including the \textsf{.pc}
directory. The \textit{make clean} target in the linux kernel sources
is an example. Quilt uses zero-length files in \textsf{.pc} to mark
files added by patches, so such packages may corrupt the \textsf{.pc}
directory. A workaround is to create a symbolic link \textsf{.pc} in the
working tree that points to a directory outside.

It may happen that the files in the \textsf{patches} directory gets out of
sync with the working tree (e.g., they may accidentally get updated by
CVS or similar). Files in the \textsf{.pc} directory may also become
inconsistent, particularly if files are not added before modifying them
(\quilt{add} / \quilt{edit}). If this happens, it may be possible to
repair the source tree, but often the best solution is to start over
with a scratch working directory and the \textsf{patches} sub-directory.
There is no need to keep any files from the \textsf{.pc} directory in
this case.

% - Patches cannot automatically be reverse applied (?)
% - Does not auto-detect is a patch has been cleanly integrated
% - Speed

% - Push a patch that is not in the series file (after changing
%   applied-patches to include the full patch name)?

% - Other back-ends (RCS etc.)

% - Pop and push modify file timestamps, which causes recompiles.
%   Ccache ameliorates this.

% - patchutils: Very useful: lsdiff, filterdiff, etc.

\section{Summary}

We have shown how the script collection \textit{quilt} solves various
problems that occur when dealing with patches to software packages.
Quilt is an obvious improvement over directly using the underlying tools
(\prog{GNU patch}, \prog{GNU diff}, etc.), and offers many features not
available with competing solutions. Join the club!

The quilt project homepage is
\url{http://savannah.nongnu.org/projects/quilt/}. There is a development
mailing list at \url{http://mail.nongnu.org/mailman/listinfo/quilt-dev}.
Additional features that fit into quilt's mode of operation are always
welcome, of course.

\begin{thebibliography}{XX}

\bibitem{akpm02}
Andrew Morton: Patch Management Scripts,
\url{http://lwn.net/Articles/13518/} and
\url{http://www.zip.com.au/~akpm/linux/patches/patch-scripts-0.9}.

\bibitem{quilt}
Andreas Gr黱bacher et al.: Patchwork Quilt,
\url{http://savannah.nongnu.org/projects/quilt}.

\bibitem{posix-2001-diff}
IEEE Std. 1003.1-2001: Standard for Information Technology, Portable
Operating System Interface (POSIX), Shell and Utilities, diff
command, pp.~317. Online version available from the The Austin Common
Standards Revision Group, \url{http://www.opengroup.org/austin/}.

\bibitem{info-diff}
\textit{GNU diff} info pages (\textsf{info Diff}), section \textit{Output
Formats.}

\bibitem{max-rpm}
Edward C. Bailey: Maximum RPM: Taking the Red Hat Package Manager to the
Limit, \url{http://www.rpm.org/max-rpm/}.

\end{thebibliography}

% Add a "quick-reference card"?

\end{document}