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