# HG changeset patch # User Bryan O'Sullivan # Date 1151475665 25200 # Node ID a25335b568258981847856322df05bea59c5c526 # Parent 339e75288632050e14b5eb29518fcb22c10a530c Progress on MQ tutorial. diff -r 339e75288632 -r a25335b56825 en/examples/mq.tutorial --- a/en/examples/mq.tutorial Mon Jun 26 12:25:11 2006 -0700 +++ b/en/examples/mq.tutorial Tue Jun 27 23:21:05 2006 -0700 @@ -3,18 +3,57 @@ #$ name: qinit -hg clone http://hg.serpentine.com/mercurial/hg mq-sandbox - +hg init mq-sandbox cd mq-sandbox +echo 'line 1' > file1 +echo 'another line 1' > file2 +hg add file1 file2 +hg commit -m'first change' hg qinit #$ name: qnew hg tip - hg qnew first.patch - +hg tip ls .hg/patches -hg tip +#$ name: qrefresh + +echo 'line 2' >> file1 +hg diff +hg qrefresh +hg diff +hg tip --style=compact --patch + +#$ name: qrefresh2 + +echo 'line 3' >> file1 +hg status +hg qrefresh +hg tip --style=compact --patch + +#$ name: qnew2 + +hg qnew second.patch +hg log --style=compact --limit=2 +echo 'line 4' >> file1 +hg qrefresh +hg tip --style=compact --patch +hg annotate file1 + +#$ name: qseries + +hg qseries +hg qapplied + +#$ name: qpop + +hg qapplied +hg qpop +hg qseries +hg qapplied +cat file1 +hg qpush +cat file1 diff -r 339e75288632 -r a25335b56825 en/mq.tex --- a/en/mq.tex Mon Jun 26 12:25:11 2006 -0700 +++ b/en/mq.tex Tue Jun 27 23:21:05 2006 -0700 @@ -153,8 +153,9 @@ \label{ex:mq:enabled} \end{figure} -You can use MQ with \emph{any} Mercurial repository; to start, simply -prepare the repository using the \hgcmd{qinit} command (see +You can use MQ with \emph{any} Mercurial repository, and its commands +only operate within that repository. To get started, simply prepare +the repository using the \hgcmd{qinit} command (see figure~\ref{ex:mq:qinit}). This command creates an empty directory called \filename{.hg/patches}, where MQ will keep its metadata. As with many Mercurial commands, the \hgcmd{qinit} command prints nothing @@ -172,15 +173,18 @@ \label{ex:mq:qnew} \end{figure} -To commence work on a new patch, use the \hgcmd{qnew} command. This +\subsection{Creating a new patch} + +To begin work on a new patch, use the \hgcmd{qnew} command. This command takes one argument, the name of the patch to create. MQ will use this as the name of an actual file in the \filename{.hg/patches} directory, as you can see in figure~\ref{ex:mq:qnew}. -Now also present in the \filename{.hg/patches} directory are two new -files, \filename{series} and \filename{status}. The \filename{series} -file lists all of the patches that MQ knows about for this repository, -with one patch per line. The \filename{status} file lists all of the +Also newly present in the \filename{.hg/patches} directory are two +other files, \filename{series} and \filename{status}. The +\filename{series} file lists all of the patches that MQ knows about +for this repository, with one patch per line. Mercurial uses the +\filename{status} file for internal book-keeping; it tracks all of the patches that MQ has \emph{applied} in this repository. \begin{note} @@ -191,6 +195,102 @@ is happening. \end{note} +Once you have created your new patch, you can edit files in the +working directory as you usually would. All of the normal Mercurial +commands, such as \hgcmd{diff} and \hgcmd{annotate}, work exactly as +they did before. +\subsection{Refreshing a patch} + +When you reach a point where you want to save your work, use the +\hgcmd{qrefresh} command (figure~\ref{ex:mq:qnew}) to update the patch +you are working on. This command folds the changes you have made in +the working directory into your patch, and updates its corresponding +changeset to contain those changes. + +\begin{figure}[h] + \interaction{mq.tutorial.qrefresh} + \caption{Refreshing a patch} + \label{ex:mq:qrefresh} +\end{figure} + +You can run \hgcmd{qrefresh} as often as you like, so it's a good way +to ``checkpoint'' your work. Reefresh your patch at an opportune +time; try an experiment; and if the experiment doesn't work out, +\hgcmd{revert} your modifications back to the last time you refreshed. + +\begin{figure}[h] + \interaction{mq.tutorial.qrefresh2} + \caption{Refresh a patch many times to accumulate changes} + \label{ex:mq:qrefresh2} +\end{figure} + +\subsection{Stacking and tracking patches} + +Once you have finished working on a patch, or need to work on another, +you can use the \hgcmd{qnew} command again to create a new patch. +Mercurial will apply this patch on top of your existing patch. See +figure~\ref{ex:mq:qnew2} for an example. Notice that the patch +contains the changes in our prior patch as part of its context (you +can see this more clearly in the output of \hgcmd{annotate}). + +\begin{figure}[h] + \interaction{mq.tutorial.qnew2} + \caption{Stacking a second patch on top of the first} + \label{ex:mq:qnew2} +\end{figure} + +So far, with the exception of \hgcmd{qnew} and \hgcmd{qrefresh}, we've +been careful to only use regular Mercurial commands. However, there +are more ``natural'' commands you can use when thinking about patches +with MQ, as illustrated in figure~\ref{ex:mq:qseries}: + +\begin{itemize} +\item The \hgcmd{qseries} command lists every patch that MQ knows + about in this repository, from oldest to newest (most recently + \emph{created}). +\item The \hgcmd{qapplied} command lists every patch that MQ has + \emph{applied} in this repository, again from oldest to newest (most + recently applied). +\end{itemize} + +\begin{figure}[h] + \interaction{mq.tutorial.qseries} + \caption{Understanding the patch stack with \hgcmd{qseries} and + \hgcmd{qapplied}} + \label{ex:mq:qseries} +\end{figure} + +\subsection{Manipulating the patch stack} + +The previous discussion implied that there must be a difference +between ``known'' and ``applied'' patches, and there is. MQ can know +about a patch without it being applied in the repository. + +An \emph{applied} patch has a corresponding changeset in the +repository, and the effects of the patch and changeset are visible in +the working directory. You can undo the application of a patch using +the \hgcmd{qpop} command. MQ still \emph{knows about} a popped patch, +but it no longer has a corresponding changeset in the repository, and +the working directory does not contain the changes made by the patch. + +\begin{figure}[h] + \interaction{mq.tutorial.qpop} + \caption{Modifying the stack of applied patches} + \label{ex:mq:qpop} +\end{figure} + +You can reapply an unapplied, or popped, patch using the \hgcmd{qpush} +command. This creates a new changeset to correspond to the patch, and +the patch's changes once again become present in the working +directory. See figure~\ref{ex:mq:qpop} for examples of \hgcmd{qpop} +and \hgcmd{qpush} in action. Notice that once we have popped a patch +or two patches, the output of \hgcmd{qseries} remains the same, while +that of \hgcmd{qapplied} has changed. + +MQ does not limit you to pushing or popping one patch. You can have +no patches, all of them, or any number in between applied at some +point in time. + %%% Local Variables: %%% mode: latex %%% TeX-master: "00book"