changeset 25:9d5b6d303ef5

Make it 2/3 through documenting MQ commands. Add a note on a few quirks of how patches represent data.

--- a/en/mq.tex	Sun Jul 09 21:47:15 2006 -0700
+++ b/en/mq.tex	Sun Jul 09 23:18:39 2006 -0700
@@ -415,6 +415,30 @@
 \filename{foo.rej} containing one hunk, and \filename{foo}, containing
 the changes made by the five successful five hunks.
 
+\subsection{Some quirks of patch representation}
+
+There are a few useful things to know about how \command{patch} works
+with files.
+\begin{itemize}
+\item This should already be obvious, but \command{patch} cannot
+  handle binary files.
+\item Neither does it care about the executable bit; it creates new
+  files as readable, but not executable.
+\item \command{patch} treats the removal of a file as a diff between
+  the file to be removed and the empty file.  So your idea of ``I
+  deleted this file'' looks like ``every line of this file was
+  deleted'' in a patch.
+\item It treats the addition of a file as a diff between the empty
+  file and the file to be added.  So in a patch, your idea of ``I
+  added this file'' looks like ``every line of this file was added''.
+\item It treats a renamed file as the removal of the old name, and the
+  addition of the new name.  This means that renamed files have a big
+  footprint in patches.  (Note also that Mercurial does not currently
+  try to infer when files have been renamed or copied in a patch.)
+\item \command{patch} cannot represent empty files, so you cannot use
+  a patch to represent the notion ``I added this empty file to the
+  tree''.
+\end{itemize}
 \subsection{Beware the fuzz}
 
 While applying a hunk at an offset, or with a fuzz factor, will often
@@ -791,6 +815,216 @@
 Once you have this hunk, you can concatenate it onto the end of your
 destination patch and continue with the remainder of
 section~\ref{sec:mq:combine}.
+\section{MQ command reference}
+\label{sec:mq:cmdref}
+
+For an overview of the commands provided by MQ, use the command
+\hgcmdargs{help}{mq}.
+
+\subsection{\hgcmd{qapplied}---print applied patches}
+
+The \hgcmd{qapplied} command prints the current stack of applied
+patches.  Patches are printed in oldest-to-newest order, so the last
+patch in the list is the ``top'' patch.
+
+\subsection{\hgcmd{qcommit}---commit changes in the queue repository}
+
+The \hgcmd{qcommit} command commits any outstanding changes in the
+\sdirname{.hg/patches} repository.  This command only works if the
+\sdirname{.hg/patches} directory is a repository, i.e.~you created the
+directory using \hgcmdargs{qinit}{\hgopt{qinit}{-c}} or ran
+\hgcmd{init} in the directory after running \hgcmd{qinit}.
+
+This command is shorthand for \hgcmdargs{commit}{--cwd .hg/patches}.
+
+\subsection{\hgcmd{qdelete}---delete a patch from the
+  \sfilename{series} file}
+
+The \hgcmd{qdelete} command removes the entry for a patch from the
+\sfilename{series} file in the \sdirname{.hg/patches} directory.  It
+does not delete the patch file, nor does it pop the patch if the patch
+is already applied.
+
+\subsection{\hgcmd{qdiff}---print a diff of the topmost applied patch}
+
+The \hgcmd{qdiff} command prints a diff of the topmost applied patch.
+It is equivalent to \hgcmdargs{diff}{-r-2:-1}.
+
+\subsection{\hgcmd{qimport}---import a third-party patch into the queue}
+
+The \hgcmd{qimport} command adds an entry for an external patch to the
+\sfilename{series} file, and copies the patch into the
+\sdirname{.hg/patches} directory.  It adds the entry immediately after
+the topmost applied patch, but does not push the patch.
+
+If the \sdirname{.hg/patches} directory is a repository,
+\hgcmd{qimport} automatically does an \hgcmd{add} of the imported
+patch.
+
+\subsection{\hgcmd{qinit}---prepare a repository to work with MQ}
+
+The \hgcmd{qinit} command prepares a repository to work with MQ.  It
+creates a directory called \sdirname{.hg/patches}.
+
+Options:
+\begin{itemize}
+\item[\hgopt{qinit}{-c}] Create \sdirname{.hg/patches} as a repository
+  in its own right.  Also creates a \sfilename{.hgignore} file that
+  will ignore the \sfilename{status} file.
+\end{itemize}
+
+When the \sdirname{.hg/patches} directory is a repository, the
+\hgcmd{qimport} and \hgcmd{qnew} commands automatically \hgcmd{add}
+new patches.
+
+\subsection{\hgcmd{qnew}---create a new patch}
+
+The \hgcmd{qnew} command creates a new patch.  It takes one mandatory
+argument, the name to use for the patch file.  The newly created patch
+is created empty by default.  It is added to the \sfilename{series}
+file after the current topmost applied patch, and is immediately
+pushed on top of that patch.
+
+If \hgcmd{qnew} finds modified files in the working directory, it will
+refuse to create a new patch unless the \hgopt{qnew}{-f} option is
+used (see below).  This behaviour allows you to \hgcmd{qrefresh} your
+topmost applied patch before you apply a new patch on top of it.
+
+Options:
+\begin{itemize}
+\item[\hgopt{qnew}{-f}] Create a new patch if the contents of the
+  working directory are modified.  Any outstanding modifications are
+  added to the newly created patch, so after this command completes,
+  the working directory will no longer be modified.
+\item[\hgopt{qnew}{-m}] Use the given text as the commit message.
+  This text will be stored at the beginning of the patch file, before
+  the patch data.
+\end{itemize}
+
+\subsection{\hgcmd{qnext}---print the name of the next patch}
+
+The \hgcmd{qnext} command prints the name name of the next patch in
+the \sfilename{series} file after the topmost applied patch.  This
+patch will become the topmost applied patch if you run \hgcmd{qpush}.
+
+\subsection{\hgcmd{qpop}---pop patches off the stack}
+
+The \hgcmd{qpop} command removes applied patches from the top of the
+stack of applied patches.  By default, it removes only one patch.
+
+This command removes the changesets that represent the popped patches
+from the repository, and updates the working directory to undo the
+effects of the patches.
+
+This command takes an optional argument, which it uses as the name or
+index of the patch to pop to.  If given a name, it will pop patches
+until the named patch is no longer applied.  If given a number,
+\hgcmd{qpop} treats the number as an index into the entries in the
+series file, counting from zero (empty lines and lines containing only
+comments do not count).  It pops patches until the patch identified by
+the given index is no longer applied.
+
+The \hgcmd{qpop} command does not read or write patches or the
+\sfilename{series} file.  It is thus safe to \hgcmd{qpop} a patch that
+you have removed from the \sfilename{series} file, or a patch that you
+have renamed or deleted entirely.  In the latter two cases, use the
+name of the patch as it was when you applied it.
+
+By default, the \hgcmd{qpop} command will not pop any patches if the
+working directory has been modified.  You can override this behaviour
+using the \hgopt{qpop}{-f} option, which reverts all modifications in
+the working directory.
+
+Options:
+\begin{itemize}
+\item[\hgopt{qpop}{-a}] Pop all applied patches.  This returns the
+  repository to its state before you applied any patches.
+\item[\hgopt{qpop}{-f}] Forcibly revert any modifications to the
+  working directory when popping.
+\item[\hgopt{qpop}{-n}] Pop a patch from the named queue.
+\end{itemize}
+
+The \hgcmd{qpop} command removes one line from the end of the
+\sfilename{status} file for each patch that it pops.
+\subsection{\hgcmd{qprev}---print the name of the previous patch}
+
+The \hgcmd{qprev} command prints the name of the patch in the
+\sfilename{series} file that comes before the topmost applied patch.
+This will become the topmost applied patch if you run \hgcmd{qpop}.
+
+\subsection{\hgcmd{qpush}---push patches onto the stack}
+
+The \hgcmd{qpush} command adds patches onto the applied stack.  By
+default, it adds only one patch.
+
+This command creates a new changeset to represent each applied patch,
+and updates the working directory to apply the effects of the patches.
+
+The data used when creating a changeset are as follows:
+\begin{itemize}
+\item The commit date and time zone are the current date and time
+  zone.  Because these data are used to compute the identity of a
+  changeset, this means that if you \hgcmd{qpop} a patch and
+  \hgcmd{qpush} it again, the changeset that you push will have a
+  different identity than the changeset you popped.
+\item The author is the same as the default used by the \hgcmd{commit}
+  command.
+\item The commit message is any text from the patch file that comes
+  before the first diff header.  If there is no such text, a default
+  commit message is used that identifies the name of the patch.
+\end{itemize}
+
+Options:
+\begin{itemize}
+\item[\hgopt{qpush}{-a}] Push all unapplied patches from the
+  \sfilename{series} file until there are none left to push.
+\item[\hgopt{qpush}{-l}] Add the name of the patch to the end
+  of the commit message.
+\item[\hgopt{qpush}{-m}] If a patch fails to apply cleanly, use the
+  entry for the patch in another saved queue to compute the parameters
+  for a three-way merge, and perform a three-way merge using the
+  normal Mercurial merge machinery.  Use the resolution of the merge
+  as the new patch content.
+\item[\hgopt{qpush}{-n}] Use the named queue if merging while pushing.
+\end{itemize}
+
+The \hgcmd{qpush} command reads, but does not modify, the
+\sfilename{series} file.  It appends one line to the \hgcmd{status}
+file for each patch that it pushes.
+
+\subsection{\hgcmd{qrefresh}---update the topmost applied patch}
+
+The \hgcmd{qrefresh} command updates the topmost applied patch.  It
+modifies the patch, removes the old changeset that represented the
+patch, and creates a new changeset to represent the modified patch.
+
+The \hgcmd{qrefresh} command looks for the following modifications:
+\begin{itemize}
+\item Changes to the commit message, i.e.~the text before the first
+  diff header in the patch file, are reflected in the new changeset
+  that represents the patch.
+\item Modifications to tracked files in the working directory are
+  added to the patch.
+\item Changes to the files tracked using \hgcmd{add}, \hgcmd{copy},
+  \hgcmd{remove}, or \hgcmd{rename}.  Added files and copy and rename
+  destinations are added to the patch, while removed files and rename
+  sources are removed.
+\end{itemize}
+
+Even if \hgcmd{qrefresh} detects no changes, it still recreates the
+changeset that represents the patch.  This causes the identity of the
+changeset to differ from the previous changeset that identified the
+patch.
+
+\section{MQ file reference}
+
+
+\subsection{The \sfilename{series} file}
+
+
+\subsection{The \sfilename{status} file}
+
+
 
 %%% Local Variables: 
 %%% mode: latex