1.1 --- a/es/mq-ref.tex	Sat Oct 18 07:48:21 2008 -0500
     1.2 +++ b/es/mq-ref.tex	Sun Oct 19 19:56:21 2008 -0500
     1.3 @@ -0,0 +1,349 @@
     1.4 +\chapter{Mercurial Queues reference}
     1.5 +\label{chap:mqref}
     1.6 +
     1.7 +\section{MQ command reference}
     1.8 +\label{sec:mqref:cmdref}
     1.9 +
    1.10 +For an overview of the commands provided by MQ, use the command
    1.11 +\hgcmdargs{help}{mq}.
    1.12 +
    1.13 +\subsection{\hgxcmd{mq}{qapplied}---print applied patches}
    1.14 +
    1.15 +The \hgxcmd{mq}{qapplied} command prints the current stack of applied
    1.16 +patches.  Patches are printed in oldest-to-newest order, so the last
    1.17 +patch in the list is the ``top'' patch.
    1.18 +
    1.19 +\subsection{\hgxcmd{mq}{qcommit}---commit changes in the queue repository}
    1.20 +
    1.21 +The \hgxcmd{mq}{qcommit} command commits any outstanding changes in the
    1.22 +\sdirname{.hg/patches} repository.  This command only works if the
    1.23 +\sdirname{.hg/patches} directory is a repository, i.e.~you created the
    1.24 +directory using \hgcmdargs{qinit}{\hgxopt{mq}{qinit}{-c}} or ran
    1.25 +\hgcmd{init} in the directory after running \hgxcmd{mq}{qinit}.
    1.26 +
    1.27 +This command is shorthand for \hgcmdargs{commit}{--cwd .hg/patches}.
    1.28 +
    1.29 +\subsection{\hgxcmd{mq}{qdelete}---delete a patch from the
    1.30 +  \sfilename{series} file}
    1.31 +
    1.32 +The \hgxcmd{mq}{qdelete} command removes the entry for a patch from the
    1.33 +\sfilename{series} file in the \sdirname{.hg/patches} directory.  It
    1.34 +does not pop the patch if the patch is already applied.  By default,
    1.35 +it does not delete the patch file; use the \hgxopt{mq}{qdel}{-f} option to
    1.36 +do that.
    1.37 +
    1.38 +Options:
    1.39 +\begin{itemize}
    1.40 +\item[\hgxopt{mq}{qdel}{-f}] Delete the patch file.
    1.41 +\end{itemize}
    1.42 +
    1.43 +\subsection{\hgxcmd{mq}{qdiff}---print a diff of the topmost applied patch}
    1.44 +
    1.45 +The \hgxcmd{mq}{qdiff} command prints a diff of the topmost applied patch.
    1.46 +It is equivalent to \hgcmdargs{diff}{-r-2:-1}.
    1.47 +
    1.48 +\subsection{\hgxcmd{mq}{qfold}---merge (``fold'') several patches into one}
    1.49 +
    1.50 +The \hgxcmd{mq}{qfold} command merges multiple patches into the topmost
    1.51 +applied patch, so that the topmost applied patch makes the union of
    1.52 +all of the changes in the patches in question.
    1.53 +
    1.54 +The patches to fold must not be applied; \hgxcmd{mq}{qfold} will exit with
    1.55 +an error if any is.  The order in which patches are folded is
    1.56 +significant; \hgcmdargs{qfold}{a b} means ``apply the current topmost
    1.57 +patch, followed by \texttt{a}, followed by \texttt{b}''.
    1.58 +
    1.59 +The comments from the folded patches are appended to the comments of
    1.60 +the destination patch, with each block of comments separated by three
    1.61 +asterisk (``\texttt{*}'') characters.  Use the \hgxopt{mq}{qfold}{-e}
    1.62 +option to edit the commit message for the combined patch/changeset
    1.63 +after the folding has completed.
    1.64 +
    1.65 +Options:
    1.66 +\begin{itemize}
    1.67 +\item[\hgxopt{mq}{qfold}{-e}] Edit the commit message and patch description
    1.68 +  for the newly folded patch.
    1.69 +\item[\hgxopt{mq}{qfold}{-l}] Use the contents of the given file as the new
    1.70 +  commit message and patch description for the folded patch.
    1.71 +\item[\hgxopt{mq}{qfold}{-m}] Use the given text as the new commit message
    1.72 +  and patch description for the folded patch.
    1.73 +\end{itemize}
    1.74 +
    1.75 +\subsection{\hgxcmd{mq}{qheader}---display the header/description of a patch}
    1.76 +
    1.77 +The \hgxcmd{mq}{qheader} command prints the header, or description, of a
    1.78 +patch.  By default, it prints the header of the topmost applied patch.
    1.79 +Given an argument, it prints the header of the named patch.
    1.80 +
    1.81 +\subsection{\hgxcmd{mq}{qimport}---import a third-party patch into the queue}
    1.82 +
    1.83 +The \hgxcmd{mq}{qimport} command adds an entry for an external patch to the
    1.84 +\sfilename{series} file, and copies the patch into the
    1.85 +\sdirname{.hg/patches} directory.  It adds the entry immediately after
    1.86 +the topmost applied patch, but does not push the patch.
    1.87 +
    1.88 +If the \sdirname{.hg/patches} directory is a repository,
    1.89 +\hgxcmd{mq}{qimport} automatically does an \hgcmd{add} of the imported
    1.90 +patch.
    1.91 +
    1.92 +\subsection{\hgxcmd{mq}{qinit}---prepare a repository to work with MQ}
    1.93 +
    1.94 +The \hgxcmd{mq}{qinit} command prepares a repository to work with MQ.  It
    1.95 +creates a directory called \sdirname{.hg/patches}.
    1.96 +
    1.97 +Options:
    1.98 +\begin{itemize}
    1.99 +\item[\hgxopt{mq}{qinit}{-c}] Create \sdirname{.hg/patches} as a repository
   1.100 +  in its own right.  Also creates a \sfilename{.hgignore} file that
   1.101 +  will ignore the \sfilename{status} file.
   1.102 +\end{itemize}
   1.103 +
   1.104 +When the \sdirname{.hg/patches} directory is a repository, the
   1.105 +\hgxcmd{mq}{qimport} and \hgxcmd{mq}{qnew} commands automatically \hgcmd{add}
   1.106 +new patches.
   1.107 +
   1.108 +\subsection{\hgxcmd{mq}{qnew}---create a new patch}
   1.109 +
   1.110 +The \hgxcmd{mq}{qnew} command creates a new patch.  It takes one mandatory
   1.111 +argument, the name to use for the patch file.  The newly created patch
   1.112 +is created empty by default.  It is added to the \sfilename{series}
   1.113 +file after the current topmost applied patch, and is immediately
   1.114 +pushed on top of that patch.
   1.115 +
   1.116 +If \hgxcmd{mq}{qnew} finds modified files in the working directory, it will
   1.117 +refuse to create a new patch unless the \hgxopt{mq}{qnew}{-f} option is
   1.118 +used (see below).  This behaviour allows you to \hgxcmd{mq}{qrefresh} your
   1.119 +topmost applied patch before you apply a new patch on top of it.
   1.120 +
   1.121 +Options:
   1.122 +\begin{itemize}
   1.123 +\item[\hgxopt{mq}{qnew}{-f}] Create a new patch if the contents of the
   1.124 +  working directory are modified.  Any outstanding modifications are
   1.125 +  added to the newly created patch, so after this command completes,
   1.126 +  the working directory will no longer be modified.
   1.127 +\item[\hgxopt{mq}{qnew}{-m}] Use the given text as the commit message.
   1.128 +  This text will be stored at the beginning of the patch file, before
   1.129 +  the patch data.
   1.130 +\end{itemize}
   1.131 +
   1.132 +\subsection{\hgxcmd{mq}{qnext}---print the name of the next patch}
   1.133 +
   1.134 +The \hgxcmd{mq}{qnext} command prints the name name of the next patch in
   1.135 +the \sfilename{series} file after the topmost applied patch.  This
   1.136 +patch will become the topmost applied patch if you run \hgxcmd{mq}{qpush}.
   1.137 +
   1.138 +\subsection{\hgxcmd{mq}{qpop}---pop patches off the stack}
   1.139 +
   1.140 +The \hgxcmd{mq}{qpop} command removes applied patches from the top of the
   1.141 +stack of applied patches.  By default, it removes only one patch.
   1.142 +
   1.143 +This command removes the changesets that represent the popped patches
   1.144 +from the repository, and updates the working directory to undo the
   1.145 +effects of the patches.
   1.146 +
   1.147 +This command takes an optional argument, which it uses as the name or
   1.148 +index of the patch to pop to.  If given a name, it will pop patches
   1.149 +until the named patch is the topmost applied patch.  If given a
   1.150 +number, \hgxcmd{mq}{qpop} treats the number as an index into the entries in
   1.151 +the series file, counting from zero (empty lines and lines containing
   1.152 +only comments do not count).  It pops patches until the patch
   1.153 +identified by the given index is the topmost applied patch.
   1.154 +
   1.155 +The \hgxcmd{mq}{qpop} command does not read or write patches or the
   1.156 +\sfilename{series} file.  It is thus safe to \hgxcmd{mq}{qpop} a patch that
   1.157 +you have removed from the \sfilename{series} file, or a patch that you
   1.158 +have renamed or deleted entirely.  In the latter two cases, use the
   1.159 +name of the patch as it was when you applied it.
   1.160 +
   1.161 +By default, the \hgxcmd{mq}{qpop} command will not pop any patches if the
   1.162 +working directory has been modified.  You can override this behaviour
   1.163 +using the \hgxopt{mq}{qpop}{-f} option, which reverts all modifications in
   1.164 +the working directory.
   1.165 +
   1.166 +Options:
   1.167 +\begin{itemize}
   1.168 +\item[\hgxopt{mq}{qpop}{-a}] Pop all applied patches.  This returns the
   1.169 +  repository to its state before you applied any patches.
   1.170 +\item[\hgxopt{mq}{qpop}{-f}] Forcibly revert any modifications to the
   1.171 +  working directory when popping.
   1.172 +\item[\hgxopt{mq}{qpop}{-n}] Pop a patch from the named queue.
   1.173 +\end{itemize}
   1.174 +
   1.175 +The \hgxcmd{mq}{qpop} command removes one line from the end of the
   1.176 +\sfilename{status} file for each patch that it pops.
   1.177 +
   1.178 +\subsection{\hgxcmd{mq}{qprev}---print the name of the previous patch}
   1.179 +
   1.180 +The \hgxcmd{mq}{qprev} command prints the name of the patch in the
   1.181 +\sfilename{series} file that comes before the topmost applied patch.
   1.182 +This will become the topmost applied patch if you run \hgxcmd{mq}{qpop}.
   1.183 +
   1.184 +\subsection{\hgxcmd{mq}{qpush}---push patches onto the stack}
   1.185 +\label{sec:mqref:cmd:qpush}
   1.186 +
   1.187 +The \hgxcmd{mq}{qpush} command adds patches onto the applied stack.  By
   1.188 +default, it adds only one patch.
   1.189 +
   1.190 +This command creates a new changeset to represent each applied patch,
   1.191 +and updates the working directory to apply the effects of the patches.
   1.192 +
   1.193 +The default data used when creating a changeset are as follows:
   1.194 +\begin{itemize}
   1.195 +\item The commit date and time zone are the current date and time
   1.196 +  zone.  Because these data are used to compute the identity of a
   1.197 +  changeset, this means that if you \hgxcmd{mq}{qpop} a patch and
   1.198 +  \hgxcmd{mq}{qpush} it again, the changeset that you push will have a
   1.199 +  different identity than the changeset you popped.
   1.200 +\item The author is the same as the default used by the \hgcmd{commit}
   1.201 +  command.
   1.202 +\item The commit message is any text from the patch file that comes
   1.203 +  before the first diff header.  If there is no such text, a default
   1.204 +  commit message is used that identifies the name of the patch.
   1.205 +\end{itemize}
   1.206 +If a patch contains a Mercurial patch header (XXX add link), the
   1.207 +information in the patch header overrides these defaults.
   1.208 +
   1.209 +Options:
   1.210 +\begin{itemize}
   1.211 +\item[\hgxopt{mq}{qpush}{-a}] Push all unapplied patches from the
   1.212 +  \sfilename{series} file until there are none left to push.
   1.213 +\item[\hgxopt{mq}{qpush}{-l}] Add the name of the patch to the end
   1.214 +  of the commit message.
   1.215 +\item[\hgxopt{mq}{qpush}{-m}] If a patch fails to apply cleanly, use the
   1.216 +  entry for the patch in another saved queue to compute the parameters
   1.217 +  for a three-way merge, and perform a three-way merge using the
   1.218 +  normal Mercurial merge machinery.  Use the resolution of the merge
   1.219 +  as the new patch content.
   1.220 +\item[\hgxopt{mq}{qpush}{-n}] Use the named queue if merging while pushing.
   1.221 +\end{itemize}
   1.222 +
   1.223 +The \hgxcmd{mq}{qpush} command reads, but does not modify, the
   1.224 +\sfilename{series} file.  It appends one line to the \hgcmd{status}
   1.225 +file for each patch that it pushes.
   1.226 +
   1.227 +\subsection{\hgxcmd{mq}{qrefresh}---update the topmost applied patch}
   1.228 +
   1.229 +The \hgxcmd{mq}{qrefresh} command updates the topmost applied patch.  It
   1.230 +modifies the patch, removes the old changeset that represented the
   1.231 +patch, and creates a new changeset to represent the modified patch.
   1.232 +
   1.233 +The \hgxcmd{mq}{qrefresh} command looks for the following modifications:
   1.234 +\begin{itemize}
   1.235 +\item Changes to the commit message, i.e.~the text before the first
   1.236 +  diff header in the patch file, are reflected in the new changeset
   1.237 +  that represents the patch.
   1.238 +\item Modifications to tracked files in the working directory are
   1.239 +  added to the patch.
   1.240 +\item Changes to the files tracked using \hgcmd{add}, \hgcmd{copy},
   1.241 +  \hgcmd{remove}, or \hgcmd{rename}.  Added files and copy and rename
   1.242 +  destinations are added to the patch, while removed files and rename
   1.243 +  sources are removed.
   1.244 +\end{itemize}
   1.245 +
   1.246 +Even if \hgxcmd{mq}{qrefresh} detects no changes, it still recreates the
   1.247 +changeset that represents the patch.  This causes the identity of the
   1.248 +changeset to differ from the previous changeset that identified the
   1.249 +patch.
   1.250 +
   1.251 +Options:
   1.252 +\begin{itemize}
   1.253 +\item[\hgxopt{mq}{qrefresh}{-e}] Modify the commit and patch description,
   1.254 +  using the preferred text editor.
   1.255 +\item[\hgxopt{mq}{qrefresh}{-m}] Modify the commit message and patch
   1.256 +  description, using the given text.
   1.257 +\item[\hgxopt{mq}{qrefresh}{-l}] Modify the commit message and patch
   1.258 +  description, using text from the given file.
   1.259 +\end{itemize}
   1.260 +
   1.261 +\subsection{\hgxcmd{mq}{qrename}---rename a patch}
   1.262 +
   1.263 +The \hgxcmd{mq}{qrename} command renames a patch, and changes the entry for
   1.264 +the patch in the \sfilename{series} file.
   1.265 +
   1.266 +With a single argument, \hgxcmd{mq}{qrename} renames the topmost applied
   1.267 +patch.  With two arguments, it renames its first argument to its
   1.268 +second.
   1.269 +
   1.270 +\subsection{\hgxcmd{mq}{qrestore}---restore saved queue state}
   1.271 +
   1.272 +XXX No idea what this does.
   1.273 +
   1.274 +\subsection{\hgxcmd{mq}{qsave}---save current queue state}
   1.275 +
   1.276 +XXX Likewise.
   1.277 +
   1.278 +\subsection{\hgxcmd{mq}{qseries}---print the entire patch series}
   1.279 +
   1.280 +The \hgxcmd{mq}{qseries} command prints the entire patch series from the
   1.281 +\sfilename{series} file.  It prints only patch names, not empty lines
   1.282 +or comments.  It prints in order from first to be applied to last.
   1.283 +
   1.284 +\subsection{\hgxcmd{mq}{qtop}---print the name of the current patch}
   1.285 +
   1.286 +The \hgxcmd{mq}{qtop} prints the name of the topmost currently applied
   1.287 +patch.
   1.288 +
   1.289 +\subsection{\hgxcmd{mq}{qunapplied}---print patches not yet applied}
   1.290 +
   1.291 +The \hgxcmd{mq}{qunapplied} command prints the names of patches from the
   1.292 +\sfilename{series} file that are not yet applied.  It prints them in
   1.293 +order from the next patch that will be pushed to the last.
   1.294 +
   1.295 +\subsection{\hgcmd{strip}---remove a revision and descendants}
   1.296 +
   1.297 +The \hgcmd{strip} command removes a revision, and all of its
   1.298 +descendants, from the repository.  It undoes the effects of the
   1.299 +removed revisions from the repository, and updates the working
   1.300 +directory to the first parent of the removed revision.
   1.301 +
   1.302 +The \hgcmd{strip} command saves a backup of the removed changesets in
   1.303 +a bundle, so that they can be reapplied if removed in error.
   1.304 +
   1.305 +Options:
   1.306 +\begin{itemize}
   1.307 +\item[\hgopt{strip}{-b}] Save unrelated changesets that are intermixed
   1.308 +  with the stripped changesets in the backup bundle.
   1.309 +\item[\hgopt{strip}{-f}] If a branch has multiple heads, remove all
   1.310 +  heads. XXX This should be renamed, and use \texttt{-f} to strip revs
   1.311 +  when there are pending changes.
   1.312 +\item[\hgopt{strip}{-n}] Do not save a backup bundle.
   1.313 +\end{itemize}
   1.314 +
   1.315 +\section{MQ file reference}
   1.316 +
   1.317 +\subsection{The \sfilename{series} file}
   1.318 +
   1.319 +The \sfilename{series} file contains a list of the names of all
   1.320 +patches that MQ can apply.  It is represented as a list of names, with
   1.321 +one name saved per line.  Leading and trailing white space in each
   1.322 +line are ignored.
   1.323 +
   1.324 +Lines may contain comments.  A comment begins with the ``\texttt{\#}''
   1.325 +character, and extends to the end of the line.  Empty lines, and lines
   1.326 +that contain only comments, are ignored.
   1.327 +
   1.328 +You will often need to edit the \sfilename{series} file by hand, hence
   1.329 +the support for comments and empty lines noted above.  For example,
   1.330 +you can comment out a patch temporarily, and \hgxcmd{mq}{qpush} will skip
   1.331 +over that patch when applying patches.  You can also change the order
   1.332 +in which patches are applied by reordering their entries in the
   1.333 +\sfilename{series} file.
   1.334 +
   1.335 +Placing the \sfilename{series} file under revision control is also
   1.336 +supported; it is a good idea to place all of the patches that it
   1.337 +refers to under revision control, as well.  If you create a patch
   1.338 +directory using the \hgxopt{mq}{qinit}{-c} option to \hgxcmd{mq}{qinit}, this
   1.339 +will be done for you automatically.
   1.340 +
   1.341 +\subsection{The \sfilename{status} file}
   1.342 +
   1.343 +The \sfilename{status} file contains the names and changeset hashes of
   1.344 +all patches that MQ currently has applied.  Unlike the
   1.345 +\sfilename{series} file, this file is not intended for editing.  You
   1.346 +should not place this file under revision control, or modify it in any
   1.347 +way.  It is used by MQ strictly for internal book-keeping.
   1.348 +
   1.349 +%%% Local Variables: 
   1.350 +%%% mode: latex
   1.351 +%%% TeX-master: "00book"
   1.352 +%%% End: