Mercurial > hgbook
changeset 322:4301500fca37
started mq.tex. it's a quite massive chank.
| author | Yoshiki Yazawa <yaz@cc.rim.or.jp> |
|---|---|
| date | Thu, 27 Mar 2008 20:32:49 +0900 |
| parents | 2b25fe6e4331 |
| children | 2d1054e1de5b |
| files | ja/mq.tex ja/todo.txt |
| diffstat | 2 files changed, 73 insertions(+), 36 deletions(-) [+] |
line wrap: on
line diff
--- a/ja/mq.tex Thu Mar 27 18:35:07 2008 +0900 +++ b/ja/mq.tex Thu Mar 27 20:32:49 2008 +0900 @@ -1,7 +1,9 @@ -\chapter{Managing change with Mercurial Queues} +%\chapter{Managing change with Mercurial Queues} +\chapter{Mercurial Queues$B$GJQ99$r4IM}$9$k(B} \label{chap:mq} -\section{The patch management problem} +%\section{The patch management problem} +\section{$B%Q%C%A4IM}$NLdBj(B} \label{sec:mq:patch-mgmt} Here is a common scenario: you need to install a software package from @@ -52,7 +54,8 @@ (or simply ``MQ''), that massively simplifies the patch management problem. -\section{The prehistory of Mercurial Queues} +%\section{The prehistory of Mercurial Queues} +\section{Mercurial Queues$BA0;K(B} \label{sec:mq:history} During the late 1990s, several Linux kernel developers started to @@ -66,7 +69,8 @@ scripts to manage hundreds (sometimes thousands) of patches on top of the Linux kernel. -\subsection{A patchwork quilt} +%\subsection{A patchwork quilt} +\subsection{$B%Q%C%A%o!<%/$N%-%k%H(B} \label{sec:mq:quilt} In early 2003, Andreas Gruenbacher and Martin Quinson borrowed the @@ -101,7 +105,8 @@ Quilt knows nothing about revision control tools, so it works equally well on top of an unpacked tarball or a Subversion working copy. -\subsection{From patchwork quilt to Mercurial Queues} +%\subsection{From patchwork quilt to Mercurial Queues} +\subsection{$B%Q%C%A%o!<%/%-%k%H$+$i(BMercurial Queues$B$X(B} \label{sec:mq:quilt-mq} In mid-2005, Chris Mason took the features of quilt and wrote an @@ -117,7 +122,8 @@ a tremendously useful piece of software to know about for situations where you cannot use Mercurial and MQ. -\section{The huge advantage of MQ} +%\section{The huge advantage of MQ} +\section{MQ$B$NBg$-$JMxE@(B} I cannot overstate the value that MQ offers through the unification of patches and revision control. @@ -152,7 +158,8 @@ command to see which changeset or patch modified a particular line of a source file. And so on. -\section{Understanding patches} +%\section{Understanding patches} +\section{$B%Q%C%A$H$O2?$+(B} \label{sec:mq:patch} Because MQ doesn't hide its patch-oriented nature, it is helpful to @@ -208,7 +215,8 @@ section~\ref{sec:mq:adv-patch}), but you should have enough information now to use MQ. -\section{Getting started with Mercurial Queues} +%\section{Getting started with Mercurial Queues} +\section{Mercurial Queues$B$r;H$C$F$_$k(B} \label{sec:mq:start} Because MQ is implemented as an extension, you must explicitly enable @@ -256,7 +264,8 @@ \label{ex:mq:qnew} \end{figure} -\subsection{Creating a new patch} +%\subsection{Creating a new patch} +\subsection{$B?7$7$$%Q%C%A$N:n@.(B} To begin work on a new patch, use the \hgxcmd{mq}{qnew} command. This command takes one argument, the name of the patch to create. MQ will @@ -283,7 +292,8 @@ commands, such as \hgcmd{diff} and \hgcmd{annotate}, work exactly as they did before. -\subsection{Refreshing a patch} +%\subsection{Refreshing a patch} +\subsection{$B%Q%C%A$N:F@8(B} When you reach a point where you want to save your work, use the \hgxcmd{mq}{qrefresh} command (figure~\ref{ex:mq:qnew}) to update the patch @@ -308,7 +318,8 @@ \label{ex:mq:qrefresh2} \end{figure} -\subsection{Stacking and tracking patches} +%\subsection{Stacking and tracking patches} +\subsection{$B%Q%C%A$N=8@Q$HDI@W(B} Once you have finished working on a patch, or need to work on another, you can use the \hgxcmd{mq}{qnew} command again to create a new patch. @@ -344,7 +355,8 @@ \label{ex:mq:qseries} \end{figure} -\subsection{Manipulating the patch stack} +%\subsection{Manipulating the patch stack} +\subsection{$B%Q%C%A%9%?%C%/$NA`:n(B} The previous discussion implied that there must be a difference between ``known'' and ``applied'' patches, and there is. MQ can @@ -380,7 +392,8 @@ \label{ex:mq:qpop} \end{figure} -\subsection{Pushing and popping many patches} +%\subsection{Pushing and popping many patches} +\subsection{$B%Q%C%A$N%W%C%7%e$H%]%C%W(B} While \hgxcmd{mq}{qpush} and \hgxcmd{mq}{qpop} each operate on a single patch at a time by default, you can push and pop many patches in one go. The @@ -395,7 +408,8 @@ \label{ex:mq:qpush-a} \end{figure} -\subsection{Safety checks, and overriding them} +%\subsection{Safety checks, and overriding them} +\subsection{$B0BA4@-%A%'%C%/$H%*!<%P%i%$%I(B} Several MQ commands check the working directory before they do anything, and fail if they find any modifications. They do this to @@ -420,7 +434,8 @@ files affected by the patch that it is popping. Be sure to read the documentation for a command's \option{-f} option before you use it! -\subsection{Working on several patches at once} +%\subsection{Working on several patches at once} +\subsection{$BJ#?t$N%Q%C%A$r0lEY$K07$&(B} The \hgxcmd{mq}{qrefresh} command always refreshes the \emph{topmost} applied patch. This means that you can suspend work on one patch (by @@ -438,14 +453,16 @@ \hgxcmd{mq}{qrefresh} the core patch, and \hgxcmd{mq}{qpush} back to the UI patch to continue where you left off. -\section{More about patches} +%\section{More about patches} +\section{$B$5$i$K%Q%C%A$K$D$$$F(B} \label{sec:mq:adv-patch} MQ uses the GNU \command{patch} command to apply patches, so it's helpful to know a few more detailed aspects of how \command{patch} works, and about patches themselves. -\subsection{The strip count} +%\subsection{The strip count} +\subsection{$B%9%H%j%C%W%+%&%s%H(B} If you look at the file headers in a patch, you will notice that the pathnames usually have an extra component on the front that isn't @@ -493,7 +510,9 @@ to apply their patch, followed by \hgcmd{addremove} to pick up any files added or removed by the patch, followed by \hgxcmd{mq}{qrefresh}. This complexity may become unnecessary; see~\bug{311} for details. -\subsection{Strategies for applying a patch} + +%\subsection{Strategies for applying a patch} +\subsection{$B%Q%C%AE,MQ$N$?$a$N@oN,(B} When \command{patch} applies a hunk, it tries a handful of successively less accurate strategies to try to make the hunk apply. @@ -527,7 +546,8 @@ \filename{foo.rej} containing one hunk, and \filename{foo}, containing the changes made by the five successful five hunks. -\subsection{Some quirks of patch representation} +%\subsection{Some quirks of patch representation} +\subsection{$B%Q%C%AI=8=$N4qL/$JE@(B} There are a few useful things to know about how \command{patch} works with files. @@ -551,7 +571,9 @@ a patch to represent the notion ``I added this empty file to the tree''. \end{itemize} -\subsection{Beware the fuzz} + +%\subsection{Beware the fuzz} +\subsection{$B[#Kf$JE@$K$D$$$F(B} While applying a hunk at an offset, or with a fuzz factor, will often be completely successful, these inexact techniques naturally leave @@ -571,7 +593,8 @@ apply with some fuzz, provided you've verified the results of the patching process in such cases. -\subsection{Handling rejection} +%\subsection{Handling rejection} +\subsection{$B%j%8%'%/%H$N<h$j07$$(B} If \hgxcmd{mq}{qpush} fails to apply a patch, it will print an error message and exit. If it has left \sfilename{.rej} files behind, it is @@ -613,7 +636,8 @@ done its job, so that you can verify its work and finish off any remaining merges. -\section{Getting the best performance out of MQ} +%\section{Getting the best performance out of MQ} +\section{MQ$B$r:GBg8B$K3hMQ$9$k(B} \label{sec:mq:perf} MQ is very efficient at handling a large number of patches. I ran @@ -653,7 +677,8 @@ counted from zero; this means that the first patch is zero, the second is one, and so on. -\section{Updating your patches when the underlying code changes} +%\section{Updating your patches when the underlying code changes} +\section{$B2<0L%3!<%I$NJQ2=$K9g$o$;$F%Q%C%A$r99?7$9$k(B} \label{sec:mq:merge} It's common to have a stack of patches on top of an underlying @@ -722,7 +747,8 @@ or \hgcmd{strip}. You can delete \sdirname{.hg/patches.\emph{N}} once you are sure that you no longer need it as a backup. -\section{Identifying patches} +%\section{Identifying patches} +\section{$B%Q%C%A$N<1JL(B} MQ commands that work with patches let you refer to a patch either by using its name or by a number. By name is obvious enough; pass the @@ -783,7 +809,8 @@ revisions. Figure~\ref{ex:mq:id} shows a few normal Mercurial commands in use with applied patches. -\section{Useful things to know about} +%\section{Useful things to know about} +\section{$BCN$C$F$*$/$Y$-$$$/$D$+$NE@(B} There are a number of aspects of MQ usage that don't fit tidily into sections of their own, but that are good to know. Here they are, in @@ -802,7 +829,8 @@ MQ will become confused. \end{itemize} -\section{Managing patches in a repository} +%\section{Managing patches in a repository} +\section{$B%j%]%8%H%jFb$G$N%Q%C%A$N4IM}(B} \label{sec:mq:repo} Because MQ's \sdirname{.hg/patches} directory resides outside a @@ -830,7 +858,8 @@ each other, all on top of an underlying source base that they may or may not control. -\subsection{MQ support for patch repositories} +%\subsection{MQ support for patch repositories} +\subsection{MQ$B$K$h$k%Q%C%A%j%]%8%H%j%5%]!<%H(B} MQ helps you to work with the \sdirname{.hg/patches} directory as a repository; when you prepare a repository for working with patches @@ -868,7 +897,8 @@ You can then issue commands of the form \cmdargs{mq}{pull} from the main repository. -\subsection{A few things to watch out for} +%\subsection{A few things to watch out for} +\subsection{$B4F;k$7$F$*$/$Y$-$$$/$D$+$NE@(B} MQ's support for working with a repository full of patches is limited in a few small respects. @@ -881,7 +911,8 @@ see those changes show up there. If you forget to do this, you can confuse MQ's idea of which patches are applied. -\section{Third party tools for working with patches} +%\section{Third party tools for working with patches} +\section{$B%Q%C%A8~$1%5!<%I%Q!<%F%#%D!<%k(B} \label{sec:mq:tools} Once you've been working with patches for a while, you'll find @@ -913,7 +944,8 @@ only touches files whose names match a particular glob pattern. See section~\ref{mq-collab:tips:interdiff} for another example. -\section{Good ways to work with patches} +%\section{Good ways to work with patches} +\section{$B9%$^$7$$%Q%C%A<h$j07$$J}K!(B} Whether you are working on a patch series to submit to a free software or open source project, or a series that you intend to treat as a @@ -943,9 +975,11 @@ changes your patch is making, while the latter makes it easy to splice hunks selectively out of one patch and into another. -\section{MQ cookbook} +%\section{MQ cookbook} +\section{MQ$B%/%C%/%V%C%/(B} -\subsection{Manage ``trivial'' patches} +%\subsection{Manage ``trivial'' patches} +\subsection{``$B%H%j%S%"%k(B''$B$J%Q%C%A$N4IM}(B} Because the overhead of dropping files into a new Mercurial repository is so low, it makes a lot of sense to manage patches this way even if @@ -970,7 +1004,8 @@ Finally, you can apply your patches on top of the new tree. \interaction{mq.tarball.repush} -\subsection{Combining entire patches} +%\subsection{Combining entire patches} +\subsection{$B%Q%C%AF1;N$r7k9g$9$k(B} \label{sec:mq:combine} MQ provides a command, \hgxcmd{mq}{qfold} that lets you combine entire @@ -985,7 +1020,8 @@ effect as if you applied first \texttt{foo}, then \texttt{bar}, followed by \texttt{quux}. -\subsection{Merging part of one patch into another} +%\subsection{Merging part of one patch into another} +\subsection{$B%Q%C%A$N0lItJ,$rJL$N%Q%C%A$X%^!<%8$9$k(B} Merging \emph{part} of one patch into another is more difficult than combining entire patches. @@ -1025,7 +1061,8 @@ destination patch and continue with the remainder of section~\ref{sec:mq:combine}. -\section{Differences between quilt and MQ} +%\section{Differences between quilt and MQ} +\section{$B%-%k%H$H(BMQ$B$N0c$$(B} If you are already familiar with quilt, MQ provides a similar command set. There are a few differences in the way that it works.