changeset 8:a25335b56825

Progress on 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

--- 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"