1.1 --- a/en/examples/mq.tutorial	Mon Jun 26 12:25:11 2006 -0700
     1.2 +++ b/en/examples/mq.tutorial	Tue Jun 27 23:21:05 2006 -0700
     1.3 @@ -3,18 +3,57 @@
     1.4  
     1.5  #$ name: qinit
     1.6  
     1.7 -hg clone http://hg.serpentine.com/mercurial/hg mq-sandbox
     1.8 -
     1.9 +hg init mq-sandbox
    1.10  cd mq-sandbox
    1.11 +echo 'line 1' > file1
    1.12 +echo 'another line 1' > file2
    1.13 +hg add file1 file2
    1.14 +hg commit -m'first change'
    1.15  
    1.16  hg qinit
    1.17  
    1.18  #$ name: qnew
    1.19  
    1.20  hg tip
    1.21 -
    1.22  hg qnew first.patch
    1.23 -
    1.24 +hg tip
    1.25  ls .hg/patches
    1.26  
    1.27 -hg tip
    1.28 +#$ name: qrefresh
    1.29 +
    1.30 +echo 'line 2' >> file1
    1.31 +hg diff
    1.32 +hg qrefresh
    1.33 +hg diff
    1.34 +hg tip --style=compact --patch
    1.35 +
    1.36 +#$ name: qrefresh2
    1.37 +
    1.38 +echo 'line 3' >> file1
    1.39 +hg status
    1.40 +hg qrefresh
    1.41 +hg tip --style=compact --patch
    1.42 +
    1.43 +#$ name: qnew2
    1.44 +
    1.45 +hg qnew second.patch
    1.46 +hg log --style=compact --limit=2
    1.47 +echo 'line 4' >> file1
    1.48 +hg qrefresh
    1.49 +hg tip --style=compact --patch
    1.50 +hg annotate file1
    1.51 +
    1.52 +#$ name: qseries
    1.53 +
    1.54 +hg qseries
    1.55 +hg qapplied
    1.56 +
    1.57 +#$ name: qpop
    1.58 +
    1.59 +hg qapplied
    1.60 +hg qpop
    1.61 +hg qseries
    1.62 +hg qapplied
    1.63 +cat file1
    1.64 +hg qpush
    1.65 +cat file1

     2.1 --- a/en/mq.tex	Mon Jun 26 12:25:11 2006 -0700
     2.2 +++ b/en/mq.tex	Tue Jun 27 23:21:05 2006 -0700
     2.3 @@ -153,8 +153,9 @@
     2.4    \label{ex:mq:enabled}
     2.5  \end{figure}
     2.6  
     2.7 -You can use MQ with \emph{any} Mercurial repository; to start, simply
     2.8 -prepare the repository using the \hgcmd{qinit} command (see
     2.9 +You can use MQ with \emph{any} Mercurial repository, and its commands
    2.10 +only operate within that repository.  To get started, simply prepare
    2.11 +the repository using the \hgcmd{qinit} command (see
    2.12  figure~\ref{ex:mq:qinit}).  This command creates an empty directory
    2.13  called \filename{.hg/patches}, where MQ will keep its metadata.  As
    2.14  with many Mercurial commands, the \hgcmd{qinit} command prints nothing
    2.15 @@ -172,15 +173,18 @@
    2.16    \label{ex:mq:qnew}
    2.17  \end{figure}
    2.18  
    2.19 -To commence work on a new patch, use the \hgcmd{qnew} command.  This
    2.20 +\subsection{Creating a new patch}
    2.21 +
    2.22 +To begin work on a new patch, use the \hgcmd{qnew} command.  This
    2.23  command takes one argument, the name of the patch to create.  MQ will
    2.24  use this as the name of an actual file in the \filename{.hg/patches}
    2.25  directory, as you can see in figure~\ref{ex:mq:qnew}.
    2.26  
    2.27 -Now also present in the \filename{.hg/patches} directory are two new
    2.28 -files, \filename{series} and \filename{status}.  The \filename{series}
    2.29 -file lists all of the patches that MQ knows about for this repository,
    2.30 -with one patch per line.  The \filename{status} file lists all of the
    2.31 +Also newly present in the \filename{.hg/patches} directory are two
    2.32 +other files, \filename{series} and \filename{status}.  The
    2.33 +\filename{series} file lists all of the patches that MQ knows about
    2.34 +for this repository, with one patch per line.  Mercurial uses the
    2.35 +\filename{status} file for internal book-keeping; it tracks all of the
    2.36  patches that MQ has \emph{applied} in this repository.
    2.37  
    2.38  \begin{note}
    2.39 @@ -191,6 +195,102 @@
    2.40    is happening.
    2.41  \end{note}
    2.42  
    2.43 +Once you have created your new patch, you can edit files in the
    2.44 +working directory as you usually would.  All of the normal Mercurial
    2.45 +commands, such as \hgcmd{diff} and \hgcmd{annotate}, work exactly as
    2.46 +they did before.
    2.47 +\subsection{Refreshing a patch}
    2.48 +
    2.49 +When you reach a point where you want to save your work, use the
    2.50 +\hgcmd{qrefresh} command (figure~\ref{ex:mq:qnew}) to update the patch
    2.51 +you are working on.  This command folds the changes you have made in
    2.52 +the working directory into your patch, and updates its corresponding
    2.53 +changeset to contain those changes.
    2.54 +
    2.55 +\begin{figure}[h]
    2.56 +  \interaction{mq.tutorial.qrefresh}
    2.57 +  \caption{Refreshing a patch}
    2.58 +  \label{ex:mq:qrefresh}
    2.59 +\end{figure}
    2.60 +
    2.61 +You can run \hgcmd{qrefresh} as often as you like, so it's a good way
    2.62 +to ``checkpoint'' your work.  Reefresh your patch at an opportune
    2.63 +time; try an experiment; and if the experiment doesn't work out,
    2.64 +\hgcmd{revert} your modifications back to the last time you refreshed.
    2.65 +
    2.66 +\begin{figure}[h]
    2.67 +  \interaction{mq.tutorial.qrefresh2}
    2.68 +  \caption{Refresh a patch many times to accumulate changes}
    2.69 +  \label{ex:mq:qrefresh2}
    2.70 +\end{figure}
    2.71 +
    2.72 +\subsection{Stacking and tracking patches}
    2.73 +
    2.74 +Once you have finished working on a patch, or need to work on another,
    2.75 +you can use the \hgcmd{qnew} command again to create a new patch.
    2.76 +Mercurial will apply this patch on top of your existing patch.  See
    2.77 +figure~\ref{ex:mq:qnew2} for an example.  Notice that the patch
    2.78 +contains the changes in our prior patch as part of its context (you
    2.79 +can see this more clearly in the output of \hgcmd{annotate}).
    2.80 +
    2.81 +\begin{figure}[h]
    2.82 +  \interaction{mq.tutorial.qnew2}
    2.83 +  \caption{Stacking a second patch on top of the first}
    2.84 +  \label{ex:mq:qnew2}
    2.85 +\end{figure}
    2.86 +
    2.87 +So far, with the exception of \hgcmd{qnew} and \hgcmd{qrefresh}, we've
    2.88 +been careful to only use regular Mercurial commands.  However, there
    2.89 +are more ``natural'' commands you can use when thinking about patches
    2.90 +with MQ, as illustrated in figure~\ref{ex:mq:qseries}:
    2.91 +
    2.92 +\begin{itemize}
    2.93 +\item The \hgcmd{qseries} command lists every patch that MQ knows
    2.94 +  about in this repository, from oldest to newest (most recently
    2.95 +  \emph{created}).
    2.96 +\item The \hgcmd{qapplied} command lists every patch that MQ has
    2.97 +  \emph{applied} in this repository, again from oldest to newest (most
    2.98 +  recently applied).
    2.99 +\end{itemize}
   2.100 +
   2.101 +\begin{figure}[h]
   2.102 +  \interaction{mq.tutorial.qseries}
   2.103 +  \caption{Understanding the patch stack with \hgcmd{qseries} and
   2.104 +    \hgcmd{qapplied}}
   2.105 +  \label{ex:mq:qseries}
   2.106 +\end{figure}
   2.107 +
   2.108 +\subsection{Manipulating the patch stack}
   2.109 +
   2.110 +The previous discussion implied that there must be a difference
   2.111 +between ``known'' and ``applied'' patches, and there is.  MQ can know
   2.112 +about a patch without it being applied in the repository.
   2.113 +
   2.114 +An \emph{applied} patch has a corresponding changeset in the
   2.115 +repository, and the effects of the patch and changeset are visible in
   2.116 +the working directory.  You can undo the application of a patch using
   2.117 +the \hgcmd{qpop} command.  MQ still \emph{knows about} a popped patch,
   2.118 +but it no longer has a corresponding changeset in the repository, and
   2.119 +the working directory does not contain the changes made by the patch.
   2.120 +
   2.121 +\begin{figure}[h]
   2.122 +  \interaction{mq.tutorial.qpop}
   2.123 +  \caption{Modifying the stack of applied patches}
   2.124 +  \label{ex:mq:qpop}
   2.125 +\end{figure}
   2.126 +
   2.127 +You can reapply an unapplied, or popped, patch using the \hgcmd{qpush}
   2.128 +command.  This creates a new changeset to correspond to the patch, and
   2.129 +the patch's changes once again become present in the working
   2.130 +directory.  See figure~\ref{ex:mq:qpop} for examples of \hgcmd{qpop}
   2.131 +and \hgcmd{qpush} in action.  Notice that once we have popped a patch
   2.132 +or two patches, the output of \hgcmd{qseries} remains the same, while
   2.133 +that of \hgcmd{qapplied} has changed.
   2.134 +
   2.135 +MQ does not limit you to pushing or popping one patch.  You can have
   2.136 +no patches, all of them, or any number in between applied at some
   2.137 +point in time.
   2.138 +
   2.139  %%% Local Variables: 
   2.140  %%% mode: latex
   2.141  %%% TeX-master: "00book"