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"