1.1 --- a/en/mq.tex	Sun Jul 09 21:47:15 2006 -0700
     1.2 +++ b/en/mq.tex	Sun Jul 09 23:18:39 2006 -0700
     1.3 @@ -415,6 +415,30 @@
     1.4  \filename{foo.rej} containing one hunk, and \filename{foo}, containing
     1.5  the changes made by the five successful five hunks.
     1.6  
     1.7 +\subsection{Some quirks of patch representation}
     1.8 +
     1.9 +There are a few useful things to know about how \command{patch} works
    1.10 +with files.
    1.11 +\begin{itemize}
    1.12 +\item This should already be obvious, but \command{patch} cannot
    1.13 +  handle binary files.
    1.14 +\item Neither does it care about the executable bit; it creates new
    1.15 +  files as readable, but not executable.
    1.16 +\item \command{patch} treats the removal of a file as a diff between
    1.17 +  the file to be removed and the empty file.  So your idea of ``I
    1.18 +  deleted this file'' looks like ``every line of this file was
    1.19 +  deleted'' in a patch.
    1.20 +\item It treats the addition of a file as a diff between the empty
    1.21 +  file and the file to be added.  So in a patch, your idea of ``I
    1.22 +  added this file'' looks like ``every line of this file was added''.
    1.23 +\item It treats a renamed file as the removal of the old name, and the
    1.24 +  addition of the new name.  This means that renamed files have a big
    1.25 +  footprint in patches.  (Note also that Mercurial does not currently
    1.26 +  try to infer when files have been renamed or copied in a patch.)
    1.27 +\item \command{patch} cannot represent empty files, so you cannot use
    1.28 +  a patch to represent the notion ``I added this empty file to the
    1.29 +  tree''.
    1.30 +\end{itemize}
    1.31  \subsection{Beware the fuzz}
    1.32  
    1.33  While applying a hunk at an offset, or with a fuzz factor, will often
    1.34 @@ -791,6 +815,216 @@
    1.35  Once you have this hunk, you can concatenate it onto the end of your
    1.36  destination patch and continue with the remainder of
    1.37  section~\ref{sec:mq:combine}.
    1.38 +\section{MQ command reference}
    1.39 +\label{sec:mq:cmdref}
    1.40 +
    1.41 +For an overview of the commands provided by MQ, use the command
    1.42 +\hgcmdargs{help}{mq}.
    1.43 +
    1.44 +\subsection{\hgcmd{qapplied}---print applied patches}
    1.45 +
    1.46 +The \hgcmd{qapplied} command prints the current stack of applied
    1.47 +patches.  Patches are printed in oldest-to-newest order, so the last
    1.48 +patch in the list is the ``top'' patch.
    1.49 +
    1.50 +\subsection{\hgcmd{qcommit}---commit changes in the queue repository}
    1.51 +
    1.52 +The \hgcmd{qcommit} command commits any outstanding changes in the
    1.53 +\sdirname{.hg/patches} repository.  This command only works if the
    1.54 +\sdirname{.hg/patches} directory is a repository, i.e.~you created the
    1.55 +directory using \hgcmdargs{qinit}{\hgopt{qinit}{-c}} or ran
    1.56 +\hgcmd{init} in the directory after running \hgcmd{qinit}.
    1.57 +
    1.58 +This command is shorthand for \hgcmdargs{commit}{--cwd .hg/patches}.
    1.59 +
    1.60 +\subsection{\hgcmd{qdelete}---delete a patch from the
    1.61 +  \sfilename{series} file}
    1.62 +
    1.63 +The \hgcmd{qdelete} command removes the entry for a patch from the
    1.64 +\sfilename{series} file in the \sdirname{.hg/patches} directory.  It
    1.65 +does not delete the patch file, nor does it pop the patch if the patch
    1.66 +is already applied.
    1.67 +
    1.68 +\subsection{\hgcmd{qdiff}---print a diff of the topmost applied patch}
    1.69 +
    1.70 +The \hgcmd{qdiff} command prints a diff of the topmost applied patch.
    1.71 +It is equivalent to \hgcmdargs{diff}{-r-2:-1}.
    1.72 +
    1.73 +\subsection{\hgcmd{qimport}---import a third-party patch into the queue}
    1.74 +
    1.75 +The \hgcmd{qimport} command adds an entry for an external patch to the
    1.76 +\sfilename{series} file, and copies the patch into the
    1.77 +\sdirname{.hg/patches} directory.  It adds the entry immediately after
    1.78 +the topmost applied patch, but does not push the patch.
    1.79 +
    1.80 +If the \sdirname{.hg/patches} directory is a repository,
    1.81 +\hgcmd{qimport} automatically does an \hgcmd{add} of the imported
    1.82 +patch.
    1.83 +
    1.84 +\subsection{\hgcmd{qinit}---prepare a repository to work with MQ}
    1.85 +
    1.86 +The \hgcmd{qinit} command prepares a repository to work with MQ.  It
    1.87 +creates a directory called \sdirname{.hg/patches}.
    1.88 +
    1.89 +Options:
    1.90 +\begin{itemize}
    1.91 +\item[\hgopt{qinit}{-c}] Create \sdirname{.hg/patches} as a repository
    1.92 +  in its own right.  Also creates a \sfilename{.hgignore} file that
    1.93 +  will ignore the \sfilename{status} file.
    1.94 +\end{itemize}
    1.95 +
    1.96 +When the \sdirname{.hg/patches} directory is a repository, the
    1.97 +\hgcmd{qimport} and \hgcmd{qnew} commands automatically \hgcmd{add}
    1.98 +new patches.
    1.99 +
   1.100 +\subsection{\hgcmd{qnew}---create a new patch}
   1.101 +
   1.102 +The \hgcmd{qnew} command creates a new patch.  It takes one mandatory
   1.103 +argument, the name to use for the patch file.  The newly created patch
   1.104 +is created empty by default.  It is added to the \sfilename{series}
   1.105 +file after the current topmost applied patch, and is immediately
   1.106 +pushed on top of that patch.
   1.107 +
   1.108 +If \hgcmd{qnew} finds modified files in the working directory, it will
   1.109 +refuse to create a new patch unless the \hgopt{qnew}{-f} option is
   1.110 +used (see below).  This behaviour allows you to \hgcmd{qrefresh} your
   1.111 +topmost applied patch before you apply a new patch on top of it.
   1.112 +
   1.113 +Options:
   1.114 +\begin{itemize}
   1.115 +\item[\hgopt{qnew}{-f}] Create a new patch if the contents of the
   1.116 +  working directory are modified.  Any outstanding modifications are
   1.117 +  added to the newly created patch, so after this command completes,
   1.118 +  the working directory will no longer be modified.
   1.119 +\item[\hgopt{qnew}{-m}] Use the given text as the commit message.
   1.120 +  This text will be stored at the beginning of the patch file, before
   1.121 +  the patch data.
   1.122 +\end{itemize}
   1.123 +
   1.124 +\subsection{\hgcmd{qnext}---print the name of the next patch}
   1.125 +
   1.126 +The \hgcmd{qnext} command prints the name name of the next patch in
   1.127 +the \sfilename{series} file after the topmost applied patch.  This
   1.128 +patch will become the topmost applied patch if you run \hgcmd{qpush}.
   1.129 +
   1.130 +\subsection{\hgcmd{qpop}---pop patches off the stack}
   1.131 +
   1.132 +The \hgcmd{qpop} command removes applied patches from the top of the
   1.133 +stack of applied patches.  By default, it removes only one patch.
   1.134 +
   1.135 +This command removes the changesets that represent the popped patches
   1.136 +from the repository, and updates the working directory to undo the
   1.137 +effects of the patches.
   1.138 +
   1.139 +This command takes an optional argument, which it uses as the name or
   1.140 +index of the patch to pop to.  If given a name, it will pop patches
   1.141 +until the named patch is no longer applied.  If given a number,
   1.142 +\hgcmd{qpop} treats the number as an index into the entries in the
   1.143 +series file, counting from zero (empty lines and lines containing only
   1.144 +comments do not count).  It pops patches until the patch identified by
   1.145 +the given index is no longer applied.
   1.146 +
   1.147 +The \hgcmd{qpop} command does not read or write patches or the
   1.148 +\sfilename{series} file.  It is thus safe to \hgcmd{qpop} a patch that
   1.149 +you have removed from the \sfilename{series} file, or a patch that you
   1.150 +have renamed or deleted entirely.  In the latter two cases, use the
   1.151 +name of the patch as it was when you applied it.
   1.152 +
   1.153 +By default, the \hgcmd{qpop} command will not pop any patches if the
   1.154 +working directory has been modified.  You can override this behaviour
   1.155 +using the \hgopt{qpop}{-f} option, which reverts all modifications in
   1.156 +the working directory.
   1.157 +
   1.158 +Options:
   1.159 +\begin{itemize}
   1.160 +\item[\hgopt{qpop}{-a}] Pop all applied patches.  This returns the
   1.161 +  repository to its state before you applied any patches.
   1.162 +\item[\hgopt{qpop}{-f}] Forcibly revert any modifications to the
   1.163 +  working directory when popping.
   1.164 +\item[\hgopt{qpop}{-n}] Pop a patch from the named queue.
   1.165 +\end{itemize}
   1.166 +
   1.167 +The \hgcmd{qpop} command removes one line from the end of the
   1.168 +\sfilename{status} file for each patch that it pops.
   1.169 +\subsection{\hgcmd{qprev}---print the name of the previous patch}
   1.170 +
   1.171 +The \hgcmd{qprev} command prints the name of the patch in the
   1.172 +\sfilename{series} file that comes before the topmost applied patch.
   1.173 +This will become the topmost applied patch if you run \hgcmd{qpop}.
   1.174 +
   1.175 +\subsection{\hgcmd{qpush}---push patches onto the stack}
   1.176 +
   1.177 +The \hgcmd{qpush} command adds patches onto the applied stack.  By
   1.178 +default, it adds only one patch.
   1.179 +
   1.180 +This command creates a new changeset to represent each applied patch,
   1.181 +and updates the working directory to apply the effects of the patches.
   1.182 +
   1.183 +The data used when creating a changeset are as follows:
   1.184 +\begin{itemize}
   1.185 +\item The commit date and time zone are the current date and time
   1.186 +  zone.  Because these data are used to compute the identity of a
   1.187 +  changeset, this means that if you \hgcmd{qpop} a patch and
   1.188 +  \hgcmd{qpush} it again, the changeset that you push will have a
   1.189 +  different identity than the changeset you popped.
   1.190 +\item The author is the same as the default used by the \hgcmd{commit}
   1.191 +  command.
   1.192 +\item The commit message is any text from the patch file that comes
   1.193 +  before the first diff header.  If there is no such text, a default
   1.194 +  commit message is used that identifies the name of the patch.
   1.195 +\end{itemize}
   1.196 +
   1.197 +Options:
   1.198 +\begin{itemize}
   1.199 +\item[\hgopt{qpush}{-a}] Push all unapplied patches from the
   1.200 +  \sfilename{series} file until there are none left to push.
   1.201 +\item[\hgopt{qpush}{-l}] Add the name of the patch to the end
   1.202 +  of the commit message.
   1.203 +\item[\hgopt{qpush}{-m}] If a patch fails to apply cleanly, use the
   1.204 +  entry for the patch in another saved queue to compute the parameters
   1.205 +  for a three-way merge, and perform a three-way merge using the
   1.206 +  normal Mercurial merge machinery.  Use the resolution of the merge
   1.207 +  as the new patch content.
   1.208 +\item[\hgopt{qpush}{-n}] Use the named queue if merging while pushing.
   1.209 +\end{itemize}
   1.210 +
   1.211 +The \hgcmd{qpush} command reads, but does not modify, the
   1.212 +\sfilename{series} file.  It appends one line to the \hgcmd{status}
   1.213 +file for each patch that it pushes.
   1.214 +
   1.215 +\subsection{\hgcmd{qrefresh}---update the topmost applied patch}
   1.216 +
   1.217 +The \hgcmd{qrefresh} command updates the topmost applied patch.  It
   1.218 +modifies the patch, removes the old changeset that represented the
   1.219 +patch, and creates a new changeset to represent the modified patch.
   1.220 +
   1.221 +The \hgcmd{qrefresh} command looks for the following modifications:
   1.222 +\begin{itemize}
   1.223 +\item Changes to the commit message, i.e.~the text before the first
   1.224 +  diff header in the patch file, are reflected in the new changeset
   1.225 +  that represents the patch.
   1.226 +\item Modifications to tracked files in the working directory are
   1.227 +  added to the patch.
   1.228 +\item Changes to the files tracked using \hgcmd{add}, \hgcmd{copy},
   1.229 +  \hgcmd{remove}, or \hgcmd{rename}.  Added files and copy and rename
   1.230 +  destinations are added to the patch, while removed files and rename
   1.231 +  sources are removed.
   1.232 +\end{itemize}
   1.233 +
   1.234 +Even if \hgcmd{qrefresh} detects no changes, it still recreates the
   1.235 +changeset that represents the patch.  This causes the identity of the
   1.236 +changeset to differ from the previous changeset that identified the
   1.237 +patch.
   1.238 +
   1.239 +\section{MQ file reference}
   1.240 +
   1.241 +
   1.242 +\subsection{The \sfilename{series} file}
   1.243 +
   1.244 +
   1.245 +\subsection{The \sfilename{status} file}
   1.246 +
   1.247 +
   1.248  
   1.249  %%% Local Variables: 
   1.250  %%% mode: latex