hgbook
changeset 25:9d5b6d303ef5
Make it 2/3 through documenting MQ commands.
Add a note on a few quirks of how patches represent data.
Add a note on a few quirks of how patches represent data.
author | Bryan O'Sullivan <bos@serpentine.com> |
---|---|
date | Sun Jul 09 23:18:39 2006 -0700 (2006-07-09) |
parents | a752b0fd3c10 |
children | 1bc6c1f0192a |
files | en/mq.tex |
line diff
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