Bryan O'Sullivan committed a25335b

Progress on MQ tutorial.

Comments (0)

Files changed (2)


 #$ name: qinit
-hg clone 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
-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
-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.
   is happening.
+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.
+  \interaction{mq.tutorial.qrefresh}
+  \caption{Refreshing a patch}
+  \label{ex:mq:qrefresh}
+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.
+  \interaction{mq.tutorial.qrefresh2}
+  \caption{Refresh a patch many times to accumulate changes}
+  \label{ex:mq:qrefresh2}
+\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}).
+  \interaction{mq.tutorial.qnew2}
+  \caption{Stacking a second patch on top of the first}
+  \label{ex:mq:qnew2}
+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}:
+\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).
+  \interaction{mq.tutorial.qseries}
+  \caption{Understanding the patch stack with \hgcmd{qseries} and
+    \hgcmd{qapplied}}
+  \label{ex:mq:qseries}
+\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.
+  \interaction{mq.tutorial.qpop}
+  \caption{Modifying the stack of applied patches}
+  \label{ex:mq:qpop}
+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"