annotate en/appA-cmdref.xml @ 658:b90b024729f1

WIP DocBook snapshot that all compiles. Mirabile dictu!

<!-- vim: set filetype=docbkxml shiftwidth=2 autoindent expandtab tw=77 : -->

<appendix id="cmdref">
<title>Command reference</title>

<para>\cmdref{add}{add files at the next commit}
\optref{add}{I}{include}
\optref{add}{X}{exclude}
\optref{add}{n}{dry-run}</para>

<para>\cmdref{diff}{print changes in history or working directory}</para>

<para>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 <xref linkend="sec:mq:patch"/>.</para>

<para>By default, this command does not print diffs for files that Mercurial
considers to contain binary data.  To control this behaviour, see the
<option role="hg-opt-diff">-a</option> and <option role="hg-opt-diff">--git</option> options.</para>

<sect2>
<title>Options</title>

<para>\loptref{diff}{nodates}</para>

<para>Omit date and time information when printing diff headers.</para>

<para>\optref{diff}{B}{ignore-blank-lines}</para>

<para>Do not print changes that only insert or delete blank lines.  A line
that contains only whitespace is not considered blank.
</para>

<para>\optref{diff}{I}{include}
</para>

<para>Include files and directories whose names match the given patterns.
</para>

<para>\optref{diff}{X}{exclude}
</para>

<para>Exclude files and directories whose names match the given patterns.
</para>

<para>\optref{diff}{a}{text}
</para>

<para>If this option is not specified, <command role="hg-cmd">hg diff</command> will refuse to print
diffs for files that it detects as binary. Specifying <option role="hg-opt-diff">-a</option>
forces <command role="hg-cmd">hg diff</command> to treat all files as text, and generate diffs for
all of them.
</para>

<para>This option is useful for files that are <quote>mostly text</quote> but have a
few embedded NUL characters.  If you use it on files that contain a
lot of binary data, its output will be incomprehensible.
</para>

<para>\optref{diff}{b}{ignore-space-change}
</para>

<para>Do not print a line if the only change to that line is in the amount
of white space it contains.
</para>

<para>\optref{diff}{g}{git}
</para>

<para>Print <command>git</command>-compatible diffs.  XXX reference a format
description.
</para>

<para>\optref{diff}{p}{show-function}
</para>

<para>Display the name of the enclosing function in a hunk header, using a
simple heuristic.  This functionality is enabled by default, so the
<option role="hg-opt-diff">-p</option> option has no effect unless you change the value of
the <envar role="rc-item-diff">showfunc</envar> config item, as in the following example.</para>

<!-- &interaction.cmdref.diff-p; -->

<para>\optref{diff}{r}{rev}
</para>

<para>Specify one or more revisions to compare.  The <command role="hg-cmd">hg diff</command> command
accepts up to two <option role="hg-opt-diff">-r</option> options to specify the revisions to
compare.
</para>

<orderedlist>
<listitem><para>Display the differences between the parent revision of the
  working directory and the working directory.
</para>
</listitem>
<listitem><para>Display the differences between the specified changeset and the
  working directory.
</para>
</listitem>
<listitem><para>Display the differences between the two specified changesets.
</para>
</listitem></orderedlist>

<para>You can specify two revisions using either two <option role="hg-opt-diff">-r</option>
options or revision range notation.  For example, the two revision
specifications below are equivalent.
</para>
<programlisting>hg diff -r 10 -r 20
hg diff -r10:20</programlisting>

<para>When you provide two revisions, Mercurial treats the order of those
revisions as significant.  Thus, <command role="hg-cmd">hg diff -r10:20</command> will
produce a diff that will transform files from their contents as of
revision 10 to their contents as of revision 20, while
<command role="hg-cmd">hg diff -r20:10</command> 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.
</para>

<para>\optref{diff}{w}{ignore-all-space}
</para>

<para>\cmdref{version}{print version and copyright information}
</para>

<para>This command displays the version of Mercurial you are running, and
its copyright license.  There are four kinds of version string that
you may see.
</para>
<itemizedlist>
<listitem><para>The string <quote><literal>unknown</literal></quote>. This version of Mercurial was
  not built in a Mercurial repository, and cannot determine its own
  version.
</para>
</listitem>
<listitem><para>A short numeric string, such as <quote><literal>1.1</literal></quote>. This is a
  build of a revision of Mercurial that was identified by a specific
  tag in the repository where it was built.  (This doesn't necessarily
  mean that you're running an official release; someone else could
  have added that tag to any revision in the repository where they
  built Mercurial.)
</para>
</listitem>
<listitem><para>A hexadecimal string, such as <quote><literal>875489e31abe</literal></quote>.  This
  is a build of the given revision of Mercurial.
</para>
</listitem>
<listitem><para>A hexadecimal string followed by a date, such as
  <quote><literal>875489e31abe+20070205</literal></quote>.  This is a build of the given
  revision of Mercurial, where the build repository contained some
  local changes that had not been committed.
</para>
</listitem></itemizedlist>

</sect2>
<sect2>
<title>Tips and tricks</title>

<sect3 id="cmdref:diff-vs-status">
<title>Why do the results of <command role="hg-cmd">hg diff</command> and <command role="hg-cmd">hg status</command> differ?</title>

<para>When you run the <command role="hg-cmd">hg status</command> 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 <command role="hg-cmd">hg diff</command> command, you may notice that it
prints diffs for only a <emphasis>subset</emphasis> of the files that <command role="hg-cmd">hg status</command>
listed.  There are two possible reasons for this.
</para>

<para>The first is that <command role="hg-cmd">hg status</command> prints some kinds of modifications
that <command role="hg-cmd">hg diff</command> doesn't normally display.  The <command role="hg-cmd">hg diff</command> 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.
</para>

<para>If you use the <option role="hg-opt-diff">--git</option> option to <command role="hg-cmd">hg diff</command>, it will
display <command>git</command>-compatible diffs that <emphasis>can</emphasis> display this
extra information.
</para>

<para>The second possible reason that <command role="hg-cmd">hg diff</command> might be printing diffs
for a subset of the files displayed by <command role="hg-cmd">hg status</command> is that if you
invoke it without any arguments, <command role="hg-cmd">hg diff</command> prints diffs against the
first parent of the working directory.  If you have run <command role="hg-cmd">hg merge</command>
to merge two changesets, but you haven't yet committed the results of
the merge, your working directory has two parents (use <command role="hg-cmd">hg parents</command>
to see them).  While <command role="hg-cmd">hg status</command> prints modifications relative to
<emphasis>both</emphasis> parents after an uncommitted merge, <command role="hg-cmd">hg diff</command> 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
<option role="hg-opt-diff">-r</option> option.  There is no way to print diffs relative to
both parents.
</para>

</sect3>
<sect3>
<title>Generating safe binary diffs</title>

<para>If you use the <option role="hg-opt-diff">-a</option> option to force Mercurial to print
diffs of files that are either <quote>mostly text</quote> or contain lots of
binary data, those diffs cannot subsequently be applied by either
Mercurial's <command role="hg-cmd">hg import</command> command or the system's <command>patch</command>
command.
</para>

<para>If you want to generate a diff of a binary file that is safe to use as
input for <command role="hg-cmd">hg import</command>, use the <command role="hg-cmd">hg diff</command>{--git} option when you
generate the patch.  The system <command>patch</command> command cannot handle
binary patches at all.
</para>

</sect3>
</sect2>
</appendix>

<!--
local variables: 
sgml-parent-document: ("00book.xml" "book" "appendix")
end:
-->