igor@402: \chapter{Command reference}
igor@402: \label{cmdref}
igor@402: 
igor@402: \cmdref{add}{add files at the next commit}
igor@402: \optref{add}{I}{include}
igor@402: \optref{add}{X}{exclude}
igor@402: \optref{add}{n}{dry-run}
igor@402: 
igor@402: \cmdref{diff}{print changes in history or working directory}
igor@402: 
igor@402: Show differences between revisions for the specified files or
igor@402: directories, using the unified diff format.  For a description of the
igor@402: unified diff format, see section~\ref{sec:mq:patch}.
igor@402: 
igor@402: By default, this command does not print diffs for files that Mercurial
igor@402: considers to contain binary data.  To control this behaviour, see the
igor@402: \hgopt{diff}{-a} and \hgopt{diff}{--git} options.
igor@402: 
igor@402: \subsection{Options}
igor@402: 
igor@402: \loptref{diff}{nodates}
igor@402: 
igor@402: Omit date and time information when printing diff headers.
igor@402: 
igor@402: \optref{diff}{B}{ignore-blank-lines}
igor@402: 
igor@402: Do not print changes that only insert or delete blank lines.  A line
igor@402: that contains only whitespace is not considered blank.
igor@402: 
igor@402: \optref{diff}{I}{include}
igor@402: 
igor@402: Include files and directories whose names match the given patterns.
igor@402: 
igor@402: \optref{diff}{X}{exclude}
igor@402: 
igor@402: Exclude files and directories whose names match the given patterns.
igor@402: 
igor@402: \optref{diff}{a}{text}
igor@402: 
igor@402: If this option is not specified, \hgcmd{diff} will refuse to print
igor@402: diffs for files that it detects as binary. Specifying \hgopt{diff}{-a}
igor@402: forces \hgcmd{diff} to treat all files as text, and generate diffs for
igor@402: all of them.
igor@402: 
igor@402: This option is useful for files that are ``mostly text'' but have a
igor@402: few embedded NUL characters.  If you use it on files that contain a
igor@402: lot of binary data, its output will be incomprehensible.
igor@402: 
igor@402: \optref{diff}{b}{ignore-space-change}
igor@402: 
igor@402: Do not print a line if the only change to that line is in the amount
igor@402: of white space it contains.
igor@402: 
igor@402: \optref{diff}{g}{git}
igor@402: 
igor@402: Print \command{git}-compatible diffs.  XXX reference a format
igor@402: description.
igor@402: 
igor@402: \optref{diff}{p}{show-function}
igor@402: 
igor@402: Display the name of the enclosing function in a hunk header, using a
igor@402: simple heuristic.  This functionality is enabled by default, so the
igor@402: \hgopt{diff}{-p} option has no effect unless you change the value of
igor@402: the \rcitem{diff}{showfunc} config item, as in the following example.
igor@402: \interaction{cmdref.diff-p}
igor@402: 
igor@402: \optref{diff}{r}{rev}
igor@402: 
igor@402: Specify one or more revisions to compare.  The \hgcmd{diff} command
igor@402: accepts up to two \hgopt{diff}{-r} options to specify the revisions to
igor@402: compare.
igor@402: 
igor@402: \begin{enumerate}
igor@402: \setcounter{enumi}{0}
igor@402: \item Display the differences between the parent revision of the
igor@402:   working directory and the working directory.
igor@402: \item Display the differences between the specified changeset and the
igor@402:   working directory.
igor@402: \item Display the differences between the two specified changesets.
igor@402: \end{enumerate}
igor@402: 
igor@402: You can specify two revisions using either two \hgopt{diff}{-r}
igor@402: options or revision range notation.  For example, the two revision
igor@402: specifications below are equivalent.
igor@402: \begin{codesample2}
igor@402:   hg diff -r 10 -r 20
igor@402:   hg diff -r10:20
igor@402: \end{codesample2}
igor@402: 
igor@402: When you provide two revisions, Mercurial treats the order of those
igor@402: revisions as significant.  Thus, \hgcmdargs{diff}{-r10:20} will
igor@402: produce a diff that will transform files from their contents as of
igor@402: revision~10 to their contents as of revision~20, while
igor@402: \hgcmdargs{diff}{-r20:10} means the opposite: the diff that will
igor@402: transform files from their revision~20 contents to their revision~10
igor@402: contents.  You cannot reverse the ordering in this way if you are
igor@402: diffing against the working directory.
igor@402: 
igor@402: \optref{diff}{w}{ignore-all-space}
igor@402: 
igor@402: \cmdref{version}{print version and copyright information}
igor@402: 
igor@402: This command displays the version of Mercurial you are running, and
igor@402: its copyright license.  There are four kinds of version string that
igor@402: you may see.
igor@402: \begin{itemize}
igor@402: \item The string ``\texttt{unknown}''. This version of Mercurial was
igor@402:   not built in a Mercurial repository, and cannot determine its own
igor@402:   version.
igor@402: \item A short numeric string, such as ``\texttt{1.1}''. This is a
igor@402:   build of a revision of Mercurial that was identified by a specific
igor@402:   tag in the repository where it was built.  (This doesn't necessarily
igor@402:   mean that you're running an official release; someone else could
igor@402:   have added that tag to any revision in the repository where they
igor@402:   built Mercurial.)
igor@402: \item A hexadecimal string, such as ``\texttt{875489e31abe}''.  This
igor@402:   is a build of the given revision of Mercurial.
igor@402: \item A hexadecimal string followed by a date, such as
igor@402:   ``\texttt{875489e31abe+20070205}''.  This is a build of the given
igor@402:   revision of Mercurial, where the build repository contained some
igor@402:   local changes that had not been committed.
igor@402: \end{itemize}
igor@402: 
igor@402: \subsection{Tips and tricks}
igor@402: 
igor@402: \subsubsection{Why do the results of \hgcmd{diff} and \hgcmd{status}
igor@402:   differ?}
igor@402: \label{cmdref:diff-vs-status}
igor@402: 
igor@402: When you run the \hgcmd{status} command, you'll see a list of files
igor@402: that Mercurial will record changes for the next time you perform a
igor@402: commit.  If you run the \hgcmd{diff} command, you may notice that it
igor@402: prints diffs for only a \emph{subset} of the files that \hgcmd{status}
igor@402: listed.  There are two possible reasons for this.
igor@402: 
igor@402: The first is that \hgcmd{status} prints some kinds of modifications
igor@402: that \hgcmd{diff} doesn't normally display.  The \hgcmd{diff} command
igor@402: normally outputs unified diffs, which don't have the ability to
igor@402: represent some changes that Mercurial can track.  Most notably,
igor@402: traditional diffs can't represent a change in whether or not a file is
igor@402: executable, but Mercurial records this information.
igor@402: 
igor@402: If you use the \hgopt{diff}{--git} option to \hgcmd{diff}, it will
igor@402: display \command{git}-compatible diffs that \emph{can} display this
igor@402: extra information.
igor@402: 
igor@402: The second possible reason that \hgcmd{diff} might be printing diffs
igor@402: for a subset of the files displayed by \hgcmd{status} is that if you
igor@402: invoke it without any arguments, \hgcmd{diff} prints diffs against the
igor@402: first parent of the working directory.  If you have run \hgcmd{merge}
igor@402: to merge two changesets, but you haven't yet committed the results of
igor@402: the merge, your working directory has two parents (use \hgcmd{parents}
igor@402: to see them).  While \hgcmd{status} prints modifications relative to
igor@402: \emph{both} parents after an uncommitted merge, \hgcmd{diff} still
igor@402: operates relative only to the first parent.  You can get it to print
igor@402: diffs relative to the second parent by specifying that parent with the
igor@402: \hgopt{diff}{-r} option.  There is no way to print diffs relative to
igor@402: both parents.
igor@402: 
igor@402: \subsubsection{Generating safe binary diffs}
igor@402: 
igor@402: If you use the \hgopt{diff}{-a} option to force Mercurial to print
igor@402: diffs of files that are either ``mostly text'' or contain lots of
igor@402: binary data, those diffs cannot subsequently be applied by either
igor@402: Mercurial's \hgcmd{import} command or the system's \command{patch}
igor@402: command.  
igor@402: 
igor@402: If you want to generate a diff of a binary file that is safe to use as
igor@402: input for \hgcmd{import}, use the \hgcmd{diff}{--git} option when you
igor@402: generate the patch.  The system \command{patch} command cannot handle
igor@402: binary patches at all.
igor@402: 
igor@402: %%% Local Variables: 
igor@402: %%% mode: latex
igor@402: %%% TeX-master: "00book"
igor@402: %%% End: