1.1 --- /dev/null	Thu Jan 01 00:00:00 1970 +0000
     1.2 +++ b/en/cmdref.tex	Thu Dec 28 16:45:56 2006 -0800
     1.3 @@ -0,0 +1,106 @@
     1.4 +\chapter{Command reference}
     1.5 +\label{cmdref}
     1.6 +
     1.7 +\cmdref{diff}
     1.8 +
     1.9 +Show differences between revisions for the specified files or
    1.10 +directories, using the unified diff format.  For a description of the
    1.11 +unified diff format, see section~\ref{sec:mq:patch}.
    1.12 +
    1.13 +\optref{diff}{-r}{--rev}
    1.14 +
    1.15 +Specify a revision to compare.
    1.16 +
    1.17 +\optref{diff}{-a}{--text}
    1.18 +
    1.19 +If this option is not specified, \hgcmd{diff} will refuse to print
    1.20 +diffs for files that it detects as binary. Specifying \hgopt{diff}{-a}
    1.21 +forces \hgcmd{diff} to treat all files as text, and generate diffs for
    1.22 +all of them.
    1.23 +
    1.24 +This option is useful for files that are ``mostly text'' but have a
    1.25 +few embedded NUL characters.  If you use it on files that are really
    1.26 +binary, its output will be incomprehensible.
    1.27 +
    1.28 +\subsection{Specifying revisions}
    1.29 +
    1.30 +The \hgcmd{diff} command accepts up to two \hgopt{diff}{-r} options to
    1.31 +specify the revisions to compare.
    1.32 +
    1.33 +\begin{enumerate}
    1.34 +\setcounter{enumi}{0}
    1.35 +\item Display the differences between the parent of the working
    1.36 +  directory and the working directory.
    1.37 +\item Display the differences between the specified changeset and the
    1.38 +  working directory.
    1.39 +\item Display the differences between the two specified changesets.
    1.40 +\end{enumerate}
    1.41 +
    1.42 +You can specify two revisions using either two \hgopt{diff}{-r}
    1.43 +options or revision range notation.  For example, the two revision
    1.44 +specifications below are equivalent.
    1.45 +\begin{codesample2}
    1.46 +  hg diff -r 10 -r 20
    1.47 +  hg diff -r10:20
    1.48 +\end{codesample2}
    1.49 +
    1.50 +When you provide two revisions, Mercurial treats the order of those
    1.51 +revisions as significant.  Thus, \hgcmdargs{diff}{-r10:20} will
    1.52 +produce a diff that will transform files from their contents as of
    1.53 +revision~10 to their contents as of revision~20, while
    1.54 +\hgcmdargs{diff}{-r20:10} means the opposite: the diff that will
    1.55 +transform files from their revision~20 contents to their revision~10
    1.56 +contents.  You cannot reverse the ordering in this way if you are
    1.57 +diffing against the working directory.
    1.58 +
    1.59 +\subsection{Why do the results of \hgcmd{diff} and \hgcmd{status}
    1.60 +  differ?}
    1.61 +\label{cmdref:diff-vs-status}
    1.62 +
    1.63 +When you run the \hgcmd{status} command, you'll see a list of files
    1.64 +that Mercurial will record changes for the next time you perform a
    1.65 +commit.  If you run the \hgcmd{diff} command, you may notice that it
    1.66 +prints diffs for only a \emph{subset} of the files that \hgcmd{status}
    1.67 +listed.  There are two possible reasons for this.
    1.68 +
    1.69 +The first is that \hgcmd{status} prints some kinds of modifications
    1.70 +that \hgcmd{diff} doesn't normally display.  The \hgcmd{diff} command
    1.71 +normally outputs unified diffs, which don't have the ability to
    1.72 +represent some changes that Mercurial can track.  Most notably,
    1.73 +traditional diffs can't represent a change in whether or not a file is
    1.74 +executable, but Mercurial records this information.
    1.75 +
    1.76 +If you use the \hgopt{diff}{--git} option to \hgcmd{diff}, it will
    1.77 +display \command{git}-compatible diffs that \emph{can} display this
    1.78 +extra information.
    1.79 +
    1.80 +The second possible reason that \hgcmd{diff} might be printing diffs
    1.81 +for a subset of the files displayed by \hgcmd{status} is that if you
    1.82 +invoke it without any arguments, \hgcmd{diff} prints diffs against the
    1.83 +first parent of the working directory.  If you have run \hgcmd{merge}
    1.84 +to merge two changesets, but you haven't yet committed the results of
    1.85 +the merge, your working directory has two parents (use \hgcmd{parents}
    1.86 +to see them).  While \hgcmd{status} prints modifications relative to
    1.87 +\emph{both} parents after an uncommitted merge, \hgcmd{diff} still
    1.88 +operates relative only to the first parent.  You can get it to print
    1.89 +diffs relative to the second parent by specifying that parent with the
    1.90 +\hgopt{diff}{-r} option.  There is no way to print diffs relative to
    1.91 +both parents.
    1.92 +
    1.93 +\subsection{Generating safe binary diffs}
    1.94 +
    1.95 +If you use the \hgopt{diff}{-a} option to force Mercurial to print
    1.96 +diffs of files that are either ``mostly text'' or contain lots of
    1.97 +binary data, those diffs cannot subsequently be applied by either
    1.98 +Mercurial's \hgcmd{import} command or the system's \command{patch}
    1.99 +command.  
   1.100 +
   1.101 +If you want to generate a diff of a binary file that is safe to use as
   1.102 +input for \hgcmd{import}, use the \hgcmd{diff}{--git} option when you
   1.103 +generate the patch.  The system \command{patch} command cannot handle
   1.104 +binary patches at all.
   1.105 +
   1.106 +%%% Local Variables: 
   1.107 +%%% mode: latex
   1.108 +%%% TeX-master: "00book"
   1.109 +%%% End: