changeset 132:e1e2f3e0256a

Start command reference, with the diff command.

--- a/en/00book.tex	Thu Dec 28 14:10:23 2006 -0800
+++ b/en/00book.tex	Thu Dec 28 16:45:56 2006 -0800
@@ -46,9 +46,10 @@
 \include{template}
 \include{mq}
 \include{mq-collab}
-\include{mq-ref}
 
 \appendix
+\include{cmdref}
+\include{mq-ref}
 \include{srcinstall}
 \include{license}
 \addcontentsline{toc}{chapter}{Bibliography}

--- a/en/99defs.tex	Thu Dec 28 14:10:23 2006 -0800
+++ b/en/99defs.tex	Thu Dec 28 16:45:56 2006 -0800
@@ -116,6 +116,12 @@
   \newcommand{\grafix}[1]{\includegraphics{#1.png}}
 \fi
 
+% Reference entry for a command.
+\newcommand{\cmdref}[1]{\section{#1}\label{cmdref:#1}\index{\texttt{#1} command}``\texttt{hg #1}''}
+
+% Reference entry for a command option.
+\newcommand{\optref}[2]{\index{\texttt{#1} command!\texttt{#2} option}\texttt{#2}}
+
 %%% Local Variables: 
 %%% mode: latex
 %%% TeX-master: "00book"

--- a/en/Makefile	Thu Dec 28 14:10:23 2006 -0800
+++ b/en/Makefile	Thu Dec 28 16:45:56 2006 -0800
@@ -7,6 +7,7 @@
 	99book.bib \
 	99defs.tex \
 	build_id.tex \
+	cmdref.tex \
 	concepts.tex \
 	daily.tex \
 	hook.tex \

--- /dev/null	Thu Jan 01 00:00:00 1970 +0000
+++ b/en/cmdref.tex	Thu Dec 28 16:45:56 2006 -0800
@@ -0,0 +1,106 @@
+\chapter{Command reference}
+\label{cmdref}
+
+\cmdref{diff}
+
+Show differences between revisions for the specified files or
+directories, using the unified diff format.  For a description of the
+unified diff format, see section~\ref{sec:mq:patch}.
+
+\optref{diff}{-r}{--rev}
+
+Specify a revision to compare.
+
+\optref{diff}{-a}{--text}
+
+If this option is not specified, \hgcmd{diff} will refuse to print
+diffs for files that it detects as binary. Specifying \hgopt{diff}{-a}
+forces \hgcmd{diff} to treat all files as text, and generate diffs for
+all of them.
+
+This option is useful for files that are ``mostly text'' but have a
+few embedded NUL characters.  If you use it on files that are really
+binary, its output will be incomprehensible.
+
+\subsection{Specifying revisions}
+
+The \hgcmd{diff} command accepts up to two \hgopt{diff}{-r} options to
+specify the revisions to compare.
+
+\begin{enumerate}
+\setcounter{enumi}{0}
+\item Display the differences between the parent of the working
+  directory and the working directory.
+\item Display the differences between the specified changeset and the
+  working directory.
+\item Display the differences between the two specified changesets.
+\end{enumerate}
+
+You can specify two revisions using either two \hgopt{diff}{-r}
+options or revision range notation.  For example, the two revision
+specifications below are equivalent.
+\begin{codesample2}
+  hg diff -r 10 -r 20
+  hg diff -r10:20
+\end{codesample2}
+
+When you provide two revisions, Mercurial treats the order of those
+revisions as significant.  Thus, \hgcmdargs{diff}{-r10:20} will
+produce a diff that will transform files from their contents as of
+revision~10 to their contents as of revision~20, while
+\hgcmdargs{diff}{-r20:10} means the opposite: the diff that will
+transform files from their revision~20 contents to their revision~10
+contents.  You cannot reverse the ordering in this way if you are
+diffing against the working directory.
+
+\subsection{Why do the results of \hgcmd{diff} and \hgcmd{status}
+  differ?}
+\label{cmdref:diff-vs-status}
+
+When you run the \hgcmd{status} command, you'll see a list of files
+that Mercurial will record changes for the next time you perform a
+commit.  If you run the \hgcmd{diff} command, you may notice that it
+prints diffs for only a \emph{subset} of the files that \hgcmd{status}
+listed.  There are two possible reasons for this.
+
+The first is that \hgcmd{status} prints some kinds of modifications
+that \hgcmd{diff} doesn't normally display.  The \hgcmd{diff} command
+normally outputs unified diffs, which don't have the ability to
+represent some changes that Mercurial can track.  Most notably,
+traditional diffs can't represent a change in whether or not a file is
+executable, but Mercurial records this information.
+
+If you use the \hgopt{diff}{--git} option to \hgcmd{diff}, it will
+display \command{git}-compatible diffs that \emph{can} display this
+extra information.
+
+The second possible reason that \hgcmd{diff} might be printing diffs
+for a subset of the files displayed by \hgcmd{status} is that if you
+invoke it without any arguments, \hgcmd{diff} prints diffs against the
+first parent of the working directory.  If you have run \hgcmd{merge}
+to merge two changesets, but you haven't yet committed the results of
+the merge, your working directory has two parents (use \hgcmd{parents}
+to see them).  While \hgcmd{status} prints modifications relative to
+\emph{both} parents after an uncommitted merge, \hgcmd{diff} still
+operates relative only to the first parent.  You can get it to print
+diffs relative to the second parent by specifying that parent with the
+\hgopt{diff}{-r} option.  There is no way to print diffs relative to
+both parents.
+
+\subsection{Generating safe binary diffs}
+
+If you use the \hgopt{diff}{-a} option to force Mercurial to print
+diffs of files that are either ``mostly text'' or contain lots of
+binary data, those diffs cannot subsequently be applied by either
+Mercurial's \hgcmd{import} command or the system's \command{patch}
+command.  
+
+If you want to generate a diff of a binary file that is safe to use as
+input for \hgcmd{import}, use the \hgcmd{diff}{--git} option when you
+generate the patch.  The system \command{patch} command cannot handle
+binary patches at all.
+
+%%% Local Variables: 
+%%% mode: latex
+%%% TeX-master: "00book"
+%%% End: