hgbook
changeset 8:a25335b56825
Progress on MQ tutorial.
author | Bryan O'Sullivan <bos@serpentine.com> |
---|---|
date | Tue Jun 27 23:21:05 2006 -0700 (2006-06-27) |
parents | 339e75288632 |
children | 76fc489c0e0b |
files | en/examples/mq.tutorial en/mq.tex |
line diff
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"