hgbook
diff en/mq.tex @ 8:a25335b56825
Progress on MQ tutorial.
author | Bryan O'Sullivan <bos@serpentine.com> |
---|---|
date | Tue Jun 27 23:21:05 2006 -0700 (2006-06-27) |
parents | 339e75288632 |
children | e9d5b4c3d16b |
line diff
1.1 --- a/en/mq.tex Mon Jun 26 12:25:11 2006 -0700 1.2 +++ b/en/mq.tex Tue Jun 27 23:21:05 2006 -0700 1.3 @@ -153,8 +153,9 @@ 1.4 \label{ex:mq:enabled} 1.5 \end{figure} 1.6 1.7 -You can use MQ with \emph{any} Mercurial repository; to start, simply 1.8 -prepare the repository using the \hgcmd{qinit} command (see 1.9 +You can use MQ with \emph{any} Mercurial repository, and its commands 1.10 +only operate within that repository. To get started, simply prepare 1.11 +the repository using the \hgcmd{qinit} command (see 1.12 figure~\ref{ex:mq:qinit}). This command creates an empty directory 1.13 called \filename{.hg/patches}, where MQ will keep its metadata. As 1.14 with many Mercurial commands, the \hgcmd{qinit} command prints nothing 1.15 @@ -172,15 +173,18 @@ 1.16 \label{ex:mq:qnew} 1.17 \end{figure} 1.18 1.19 -To commence work on a new patch, use the \hgcmd{qnew} command. This 1.20 +\subsection{Creating a new patch} 1.21 + 1.22 +To begin work on a new patch, use the \hgcmd{qnew} command. This 1.23 command takes one argument, the name of the patch to create. MQ will 1.24 use this as the name of an actual file in the \filename{.hg/patches} 1.25 directory, as you can see in figure~\ref{ex:mq:qnew}. 1.26 1.27 -Now also present in the \filename{.hg/patches} directory are two new 1.28 -files, \filename{series} and \filename{status}. The \filename{series} 1.29 -file lists all of the patches that MQ knows about for this repository, 1.30 -with one patch per line. The \filename{status} file lists all of the 1.31 +Also newly present in the \filename{.hg/patches} directory are two 1.32 +other files, \filename{series} and \filename{status}. The 1.33 +\filename{series} file lists all of the patches that MQ knows about 1.34 +for this repository, with one patch per line. Mercurial uses the 1.35 +\filename{status} file for internal book-keeping; it tracks all of the 1.36 patches that MQ has \emph{applied} in this repository. 1.37 1.38 \begin{note} 1.39 @@ -191,6 +195,102 @@ 1.40 is happening. 1.41 \end{note} 1.42 1.43 +Once you have created your new patch, you can edit files in the 1.44 +working directory as you usually would. All of the normal Mercurial 1.45 +commands, such as \hgcmd{diff} and \hgcmd{annotate}, work exactly as 1.46 +they did before. 1.47 +\subsection{Refreshing a patch} 1.48 + 1.49 +When you reach a point where you want to save your work, use the 1.50 +\hgcmd{qrefresh} command (figure~\ref{ex:mq:qnew}) to update the patch 1.51 +you are working on. This command folds the changes you have made in 1.52 +the working directory into your patch, and updates its corresponding 1.53 +changeset to contain those changes. 1.54 + 1.55 +\begin{figure}[h] 1.56 + \interaction{mq.tutorial.qrefresh} 1.57 + \caption{Refreshing a patch} 1.58 + \label{ex:mq:qrefresh} 1.59 +\end{figure} 1.60 + 1.61 +You can run \hgcmd{qrefresh} as often as you like, so it's a good way 1.62 +to ``checkpoint'' your work. Reefresh your patch at an opportune 1.63 +time; try an experiment; and if the experiment doesn't work out, 1.64 +\hgcmd{revert} your modifications back to the last time you refreshed. 1.65 + 1.66 +\begin{figure}[h] 1.67 + \interaction{mq.tutorial.qrefresh2} 1.68 + \caption{Refresh a patch many times to accumulate changes} 1.69 + \label{ex:mq:qrefresh2} 1.70 +\end{figure} 1.71 + 1.72 +\subsection{Stacking and tracking patches} 1.73 + 1.74 +Once you have finished working on a patch, or need to work on another, 1.75 +you can use the \hgcmd{qnew} command again to create a new patch. 1.76 +Mercurial will apply this patch on top of your existing patch. See 1.77 +figure~\ref{ex:mq:qnew2} for an example. Notice that the patch 1.78 +contains the changes in our prior patch as part of its context (you 1.79 +can see this more clearly in the output of \hgcmd{annotate}). 1.80 + 1.81 +\begin{figure}[h] 1.82 + \interaction{mq.tutorial.qnew2} 1.83 + \caption{Stacking a second patch on top of the first} 1.84 + \label{ex:mq:qnew2} 1.85 +\end{figure} 1.86 + 1.87 +So far, with the exception of \hgcmd{qnew} and \hgcmd{qrefresh}, we've 1.88 +been careful to only use regular Mercurial commands. However, there 1.89 +are more ``natural'' commands you can use when thinking about patches 1.90 +with MQ, as illustrated in figure~\ref{ex:mq:qseries}: 1.91 + 1.92 +\begin{itemize} 1.93 +\item The \hgcmd{qseries} command lists every patch that MQ knows 1.94 + about in this repository, from oldest to newest (most recently 1.95 + \emph{created}). 1.96 +\item The \hgcmd{qapplied} command lists every patch that MQ has 1.97 + \emph{applied} in this repository, again from oldest to newest (most 1.98 + recently applied). 1.99 +\end{itemize} 1.100 + 1.101 +\begin{figure}[h] 1.102 + \interaction{mq.tutorial.qseries} 1.103 + \caption{Understanding the patch stack with \hgcmd{qseries} and 1.104 + \hgcmd{qapplied}} 1.105 + \label{ex:mq:qseries} 1.106 +\end{figure} 1.107 + 1.108 +\subsection{Manipulating the patch stack} 1.109 + 1.110 +The previous discussion implied that there must be a difference 1.111 +between ``known'' and ``applied'' patches, and there is. MQ can know 1.112 +about a patch without it being applied in the repository. 1.113 + 1.114 +An \emph{applied} patch has a corresponding changeset in the 1.115 +repository, and the effects of the patch and changeset are visible in 1.116 +the working directory. You can undo the application of a patch using 1.117 +the \hgcmd{qpop} command. MQ still \emph{knows about} a popped patch, 1.118 +but it no longer has a corresponding changeset in the repository, and 1.119 +the working directory does not contain the changes made by the patch. 1.120 + 1.121 +\begin{figure}[h] 1.122 + \interaction{mq.tutorial.qpop} 1.123 + \caption{Modifying the stack of applied patches} 1.124 + \label{ex:mq:qpop} 1.125 +\end{figure} 1.126 + 1.127 +You can reapply an unapplied, or popped, patch using the \hgcmd{qpush} 1.128 +command. This creates a new changeset to correspond to the patch, and 1.129 +the patch's changes once again become present in the working 1.130 +directory. See figure~\ref{ex:mq:qpop} for examples of \hgcmd{qpop} 1.131 +and \hgcmd{qpush} in action. Notice that once we have popped a patch 1.132 +or two patches, the output of \hgcmd{qseries} remains the same, while 1.133 +that of \hgcmd{qapplied} has changed. 1.134 + 1.135 +MQ does not limit you to pushing or popping one patch. You can have 1.136 +no patches, all of them, or any number in between applied at some 1.137 +point in time. 1.138 + 1.139 %%% Local Variables: 1.140 %%% mode: latex 1.141 %%% TeX-master: "00book"