bos@559: <!-- vim: set filetype=docbkxml shiftwidth=2 autoindent expandtab tw=77 : -->
bos@559: 
bos@559: <appendix id="cmdref">
bos@559: <title>Command reference</title>
bos@559: 
bos@559: <para>\cmdref{add}{add files at the next commit}
bos@133: \optref{add}{I}{include}
bos@133: \optref{add}{X}{exclude}
bos@559: \optref{add}{n}{dry-run}</para>
bos@559: 
bos@559: <para>\cmdref{diff}{print changes in history or working directory}</para>
bos@559: 
bos@559: <para>Show differences between revisions for the specified files or
bos@132: directories, using the unified diff format.  For a description of the
dongsheng@625: unified diff format, see section <xref linkend="sec.mq.patch"/>.</para>
bos@559: 
bos@559: <para>By default, this command does not print diffs for files that Mercurial
bos@133: considers to contain binary data.  To control this behaviour, see the
bos@559: <option role="hg-opt-diff">-a</option> and <option role="hg-opt-diff">--git</option> options.</para>
bos@559: 
bos@559: <sect2>
bos@559: <title>Options</title>
bos@559: 
bos@559: <para>\loptref{diff}{nodates}</para>
bos@559: 
bos@559: <para>Omit date and time information when printing diff headers.</para>
bos@559: 
bos@559: <para>\optref{diff}{B}{ignore-blank-lines}</para>
bos@559: 
bos@559: <para>Do not print changes that only insert or delete blank lines.  A line
bos@133: that contains only whitespace is not considered blank.
bos@559: </para>
bos@559: 
bos@559: <para>\optref{diff}{I}{include}
bos@559: </para>
bos@559: 
bos@559: <para>Include files and directories whose names match the given patterns.
bos@559: </para>
bos@559: 
bos@559: <para>\optref{diff}{X}{exclude}
bos@559: </para>
bos@559: 
bos@559: <para>Exclude files and directories whose names match the given patterns.
bos@559: </para>
bos@559: 
bos@559: <para>\optref{diff}{a}{text}
bos@559: </para>
bos@559: 
bos@559: <para>If this option is not specified, <command role="hg-cmd">hg diff</command> will refuse to print
bos@559: diffs for files that it detects as binary. Specifying <option role="hg-opt-diff">-a</option>
bos@559: forces <command role="hg-cmd">hg diff</command> to treat all files as text, and generate diffs for
bos@132: all of them.
bos@559: </para>
bos@559: 
bos@559: <para>This option is useful for files that are <quote>mostly text</quote> but have a
bos@133: few embedded NUL characters.  If you use it on files that contain a
bos@133: lot of binary data, its output will be incomprehensible.
bos@559: </para>
bos@559: 
bos@559: <para>\optref{diff}{b}{ignore-space-change}
bos@559: </para>
bos@559: 
bos@559: <para>Do not print a line if the only change to that line is in the amount
bos@133: of white space it contains.
bos@559: </para>
bos@559: 
bos@559: <para>\optref{diff}{g}{git}
bos@559: </para>
bos@559: 
bos@559: <para>Print <command>git</command>-compatible diffs.  XXX reference a format
bos@133: description.
bos@559: </para>
bos@559: 
bos@559: <para>\optref{diff}{p}{show-function}
bos@559: </para>
bos@559: 
bos@559: <para>Display the name of the enclosing function in a hunk header, using a
bos@133: simple heuristic.  This functionality is enabled by default, so the
bos@559: <option role="hg-opt-diff">-p</option> option has no effect unless you change the value of
bos@559: the <envar role="rc-item-diff">showfunc</envar> config item, as in the following example.</para>
bos@559: 
bos@559: <!-- &interaction.cmdref.diff-p; -->
bos@559: 
bos@559: <para>\optref{diff}{r}{rev}
bos@559: </para>
bos@559: 
bos@559: <para>Specify one or more revisions to compare.  The <command role="hg-cmd">hg diff</command> command
bos@559: accepts up to two <option role="hg-opt-diff">-r</option> options to specify the revisions to
bos@133: compare.
bos@559: </para>
bos@559: 
bos@559: <orderedlist>
bos@559: <listitem><para>Display the differences between the parent revision of the
bos@133:   working directory and the working directory.
bos@559: </para>
bos@559: </listitem>
bos@559: <listitem><para>Display the differences between the specified changeset and the
bos@132:   working directory.
bos@559: </para>
bos@559: </listitem>
bos@559: <listitem><para>Display the differences between the two specified changesets.
bos@559: </para>
bos@559: </listitem></orderedlist>
bos@559: 
bos@559: <para>You can specify two revisions using either two <option role="hg-opt-diff">-r</option>
bos@132: options or revision range notation.  For example, the two revision
bos@132: specifications below are equivalent.
bos@559: </para>
bos@559: <programlisting>hg diff -r 10 -r 20
bos@559: hg diff -r10:20</programlisting>
bos@559: 
bos@559: <para>When you provide two revisions, Mercurial treats the order of those
bos@559: revisions as significant.  Thus, <command role="hg-cmd">hg diff -r10:20</command> will
bos@132: produce a diff that will transform files from their contents as of
bos@559: revision 10 to their contents as of revision 20, while
bos@559: <command role="hg-cmd">hg diff -r20:10</command> means the opposite: the diff that will
bos@559: 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@559: </para>
bos@559: 
bos@559: <para>\optref{diff}{w}{ignore-all-space}
bos@559: </para>
bos@559: 
bos@559: <para>\cmdref{version}{print version and copyright information}
bos@559: </para>
bos@559: 
bos@559: <para>This command displays the version of Mercurial you are running, and
bos@133: its copyright license.  There are four kinds of version string that
bos@133: you may see.
bos@559: </para>
bos@559: <itemizedlist>
bos@559: <listitem><para>The string <quote><literal>unknown</literal></quote>. This version of Mercurial was
bos@133:   not built in a Mercurial repository, and cannot determine its own
bos@133:   version.
bos@559: </para>
bos@559: </listitem>
bos@559: <listitem><para>A short numeric string, such as <quote><literal>1.1</literal></quote>. This is a
bos@133:   build of a revision of Mercurial that was identified by a specific
bos@133:   tag in the repository where it was built.  (This doesn't necessarily
bos@133:   mean that you're running an official release; someone else could
bos@133:   have added that tag to any revision in the repository where they
bos@133:   built Mercurial.)
bos@559: </para>
bos@559: </listitem>
bos@559: <listitem><para>A hexadecimal string, such as <quote><literal>875489e31abe</literal></quote>.  This
bos@133:   is a build of the given revision of Mercurial.
bos@559: </para>
bos@559: </listitem>
bos@559: <listitem><para>A hexadecimal string followed by a date, such as
bos@559:   <quote><literal>875489e31abe+20070205</literal></quote>.  This is a build of the given
bos@133:   revision of Mercurial, where the build repository contained some
bos@133:   local changes that had not been committed.
bos@559: </para>
bos@559: </listitem></itemizedlist>
bos@559: 
bos@559: </sect2>
bos@559: <sect2>
bos@559: <title>Tips and tricks</title>
bos@559: 
dongsheng@625: <sect3 id="cmdref.diff-vs-status">
bos@559: <title>Why do the results of <command role="hg-cmd">hg diff</command> and <command role="hg-cmd">hg status</command> differ?</title>
bos@559: 
bos@559: <para>When you run the <command role="hg-cmd">hg status</command> command, you'll see a list of files
bos@132: that Mercurial will record changes for the next time you perform a
bos@559: commit.  If you run the <command role="hg-cmd">hg diff</command> command, you may notice that it
bos@559: prints diffs for only a <emphasis>subset</emphasis> of the files that <command role="hg-cmd">hg status</command>
bos@132: listed.  There are two possible reasons for this.
bos@559: </para>
bos@559: 
bos@559: <para>The first is that <command role="hg-cmd">hg status</command> prints some kinds of modifications
bos@559: that <command role="hg-cmd">hg diff</command> doesn't normally display.  The <command role="hg-cmd">hg diff</command> 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@559: </para>
bos@559: 
bos@559: <para>If you use the <option role="hg-opt-diff">--git</option> option to <command role="hg-cmd">hg diff</command>, it will
bos@559: display <command>git</command>-compatible diffs that <emphasis>can</emphasis> display this
bos@132: extra information.
bos@559: </para>
bos@559: 
bos@559: <para>The second possible reason that <command role="hg-cmd">hg diff</command> might be printing diffs
bos@559: for a subset of the files displayed by <command role="hg-cmd">hg status</command> is that if you
bos@559: invoke it without any arguments, <command role="hg-cmd">hg diff</command> prints diffs against the
bos@559: first parent of the working directory.  If you have run <command role="hg-cmd">hg merge</command>
bos@132: to merge two changesets, but you haven't yet committed the results of
bos@559: the merge, your working directory has two parents (use <command role="hg-cmd">hg parents</command>
bos@559: to see them).  While <command role="hg-cmd">hg status</command> prints modifications relative to
bos@559: <emphasis>both</emphasis> parents after an uncommitted merge, <command role="hg-cmd">hg diff</command> 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@559: <option role="hg-opt-diff">-r</option> option.  There is no way to print diffs relative to
bos@132: both parents.
bos@559: </para>
bos@559: 
bos@559: </sect3>
bos@559: <sect3>
bos@559: <title>Generating safe binary diffs</title>
bos@559: 
bos@559: <para>If you use the <option role="hg-opt-diff">-a</option> option to force Mercurial to print
bos@559: diffs of files that are either <quote>mostly text</quote> or contain lots of
bos@132: binary data, those diffs cannot subsequently be applied by either
bos@559: Mercurial's <command role="hg-cmd">hg import</command> command or the system's <command>patch</command>
bos@559: command.
bos@559: </para>
bos@559: 
bos@559: <para>If you want to generate a diff of a binary file that is safe to use as
bos@559: input for <command role="hg-cmd">hg import</command>, use the <command role="hg-cmd">hg diff</command>{--git} option when you
bos@559: generate the patch.  The system <command>patch</command> command cannot handle
bos@132: binary patches at all.
bos@559: </para>
bos@559: 
bos@559: </sect3>
bos@559: </sect2>
bos@559: </appendix>
bos@559: 
bos@559: <!--
bos@559: local variables: 
bos@559: sgml-parent-document: ("00book.xml" "book" "appendix")
bos@559: end:
bos@559: -->