1.1 --- /dev/null	Thu Jan 01 00:00:00 1970 +0000
     1.2 +++ b/en/appA-cmdref.xml	Wed Feb 18 00:22:09 2009 -0800
     1.3 @@ -0,0 +1,223 @@
     1.4 +<!-- vim: set filetype=docbkxml shiftwidth=2 autoindent expandtab tw=77 : -->
     1.5 +
     1.6 +<appendix id="cmdref">
     1.7 +<title>Command reference</title>
     1.8 +
     1.9 +<para>\cmdref{add}{add files at the next commit}
    1.10 +\optref{add}{I}{include}
    1.11 +\optref{add}{X}{exclude}
    1.12 +\optref{add}{n}{dry-run}</para>
    1.13 +
    1.14 +<para>\cmdref{diff}{print changes in history or working directory}</para>
    1.15 +
    1.16 +<para>Show differences between revisions for the specified files or
    1.17 +directories, using the unified diff format.  For a description of the
    1.18 +unified diff format, see section <xref linkend="sec:mq:patch"/>.</para>
    1.19 +
    1.20 +<para>By default, this command does not print diffs for files that Mercurial
    1.21 +considers to contain binary data.  To control this behaviour, see the
    1.22 +<option role="hg-opt-diff">-a</option> and <option role="hg-opt-diff">--git</option> options.</para>
    1.23 +
    1.24 +<sect2>
    1.25 +<title>Options</title>
    1.26 +
    1.27 +<para>\loptref{diff}{nodates}</para>
    1.28 +
    1.29 +<para>Omit date and time information when printing diff headers.</para>
    1.30 +
    1.31 +<para>\optref{diff}{B}{ignore-blank-lines}</para>
    1.32 +
    1.33 +<para>Do not print changes that only insert or delete blank lines.  A line
    1.34 +that contains only whitespace is not considered blank.
    1.35 +</para>
    1.36 +
    1.37 +<para>\optref{diff}{I}{include}
    1.38 +</para>
    1.39 +
    1.40 +<para>Include files and directories whose names match the given patterns.
    1.41 +</para>
    1.42 +
    1.43 +<para>\optref{diff}{X}{exclude}
    1.44 +</para>
    1.45 +
    1.46 +<para>Exclude files and directories whose names match the given patterns.
    1.47 +</para>
    1.48 +
    1.49 +<para>\optref{diff}{a}{text}
    1.50 +</para>
    1.51 +
    1.52 +<para>If this option is not specified, <command role="hg-cmd">hg diff</command> will refuse to print
    1.53 +diffs for files that it detects as binary. Specifying <option role="hg-opt-diff">-a</option>
    1.54 +forces <command role="hg-cmd">hg diff</command> to treat all files as text, and generate diffs for
    1.55 +all of them.
    1.56 +</para>
    1.57 +
    1.58 +<para>This option is useful for files that are <quote>mostly text</quote> but have a
    1.59 +few embedded NUL characters.  If you use it on files that contain a
    1.60 +lot of binary data, its output will be incomprehensible.
    1.61 +</para>
    1.62 +
    1.63 +<para>\optref{diff}{b}{ignore-space-change}
    1.64 +</para>
    1.65 +
    1.66 +<para>Do not print a line if the only change to that line is in the amount
    1.67 +of white space it contains.
    1.68 +</para>
    1.69 +
    1.70 +<para>\optref{diff}{g}{git}
    1.71 +</para>
    1.72 +
    1.73 +<para>Print <command>git</command>-compatible diffs.  XXX reference a format
    1.74 +description.
    1.75 +</para>
    1.76 +
    1.77 +<para>\optref{diff}{p}{show-function}
    1.78 +</para>
    1.79 +
    1.80 +<para>Display the name of the enclosing function in a hunk header, using a
    1.81 +simple heuristic.  This functionality is enabled by default, so the
    1.82 +<option role="hg-opt-diff">-p</option> option has no effect unless you change the value of
    1.83 +the <envar role="rc-item-diff">showfunc</envar> config item, as in the following example.</para>
    1.84 +
    1.85 +<!-- &interaction.cmdref.diff-p; -->
    1.86 +
    1.87 +<para>\optref{diff}{r}{rev}
    1.88 +</para>
    1.89 +
    1.90 +<para>Specify one or more revisions to compare.  The <command role="hg-cmd">hg diff</command> command
    1.91 +accepts up to two <option role="hg-opt-diff">-r</option> options to specify the revisions to
    1.92 +compare.
    1.93 +</para>
    1.94 +
    1.95 +<orderedlist>
    1.96 +<listitem><para>Display the differences between the parent revision of the
    1.97 +  working directory and the working directory.
    1.98 +</para>
    1.99 +</listitem>
   1.100 +<listitem><para>Display the differences between the specified changeset and the
   1.101 +  working directory.
   1.102 +</para>
   1.103 +</listitem>
   1.104 +<listitem><para>Display the differences between the two specified changesets.
   1.105 +</para>
   1.106 +</listitem></orderedlist>
   1.107 +
   1.108 +<para>You can specify two revisions using either two <option role="hg-opt-diff">-r</option>
   1.109 +options or revision range notation.  For example, the two revision
   1.110 +specifications below are equivalent.
   1.111 +</para>
   1.112 +<programlisting>hg diff -r 10 -r 20
   1.113 +hg diff -r10:20</programlisting>
   1.114 +
   1.115 +<para>When you provide two revisions, Mercurial treats the order of those
   1.116 +revisions as significant.  Thus, <command role="hg-cmd">hg diff -r10:20</command> will
   1.117 +produce a diff that will transform files from their contents as of
   1.118 +revision 10 to their contents as of revision 20, while
   1.119 +<command role="hg-cmd">hg diff -r20:10</command> means the opposite: the diff that will
   1.120 +transform files from their revision 20 contents to their revision 10
   1.121 +contents.  You cannot reverse the ordering in this way if you are
   1.122 +diffing against the working directory.
   1.123 +</para>
   1.124 +
   1.125 +<para>\optref{diff}{w}{ignore-all-space}
   1.126 +</para>
   1.127 +
   1.128 +<para>\cmdref{version}{print version and copyright information}
   1.129 +</para>
   1.130 +
   1.131 +<para>This command displays the version of Mercurial you are running, and
   1.132 +its copyright license.  There are four kinds of version string that
   1.133 +you may see.
   1.134 +</para>
   1.135 +<itemizedlist>
   1.136 +<listitem><para>The string <quote><literal>unknown</literal></quote>. This version of Mercurial was
   1.137 +  not built in a Mercurial repository, and cannot determine its own
   1.138 +  version.
   1.139 +</para>
   1.140 +</listitem>
   1.141 +<listitem><para>A short numeric string, such as <quote><literal>1.1</literal></quote>. This is a
   1.142 +  build of a revision of Mercurial that was identified by a specific
   1.143 +  tag in the repository where it was built.  (This doesn't necessarily
   1.144 +  mean that you're running an official release; someone else could
   1.145 +  have added that tag to any revision in the repository where they
   1.146 +  built Mercurial.)
   1.147 +</para>
   1.148 +</listitem>
   1.149 +<listitem><para>A hexadecimal string, such as <quote><literal>875489e31abe</literal></quote>.  This
   1.150 +  is a build of the given revision of Mercurial.
   1.151 +</para>
   1.152 +</listitem>
   1.153 +<listitem><para>A hexadecimal string followed by a date, such as
   1.154 +  <quote><literal>875489e31abe+20070205</literal></quote>.  This is a build of the given
   1.155 +  revision of Mercurial, where the build repository contained some
   1.156 +  local changes that had not been committed.
   1.157 +</para>
   1.158 +</listitem></itemizedlist>
   1.159 +
   1.160 +</sect2>
   1.161 +<sect2>
   1.162 +<title>Tips and tricks</title>
   1.163 +
   1.164 +<sect3 id="cmdref:diff-vs-status">
   1.165 +<title>Why do the results of <command role="hg-cmd">hg diff</command> and <command role="hg-cmd">hg status</command> differ?</title>
   1.166 +
   1.167 +<para>When you run the <command role="hg-cmd">hg status</command> command, you'll see a list of files
   1.168 +that Mercurial will record changes for the next time you perform a
   1.169 +commit.  If you run the <command role="hg-cmd">hg diff</command> command, you may notice that it
   1.170 +prints diffs for only a <emphasis>subset</emphasis> of the files that <command role="hg-cmd">hg status</command>
   1.171 +listed.  There are two possible reasons for this.
   1.172 +</para>
   1.173 +
   1.174 +<para>The first is that <command role="hg-cmd">hg status</command> prints some kinds of modifications
   1.175 +that <command role="hg-cmd">hg diff</command> doesn't normally display.  The <command role="hg-cmd">hg diff</command> command
   1.176 +normally outputs unified diffs, which don't have the ability to
   1.177 +represent some changes that Mercurial can track.  Most notably,
   1.178 +traditional diffs can't represent a change in whether or not a file is
   1.179 +executable, but Mercurial records this information.
   1.180 +</para>
   1.181 +
   1.182 +<para>If you use the <option role="hg-opt-diff">--git</option> option to <command role="hg-cmd">hg diff</command>, it will
   1.183 +display <command>git</command>-compatible diffs that <emphasis>can</emphasis> display this
   1.184 +extra information.
   1.185 +</para>
   1.186 +
   1.187 +<para>The second possible reason that <command role="hg-cmd">hg diff</command> might be printing diffs
   1.188 +for a subset of the files displayed by <command role="hg-cmd">hg status</command> is that if you
   1.189 +invoke it without any arguments, <command role="hg-cmd">hg diff</command> prints diffs against the
   1.190 +first parent of the working directory.  If you have run <command role="hg-cmd">hg merge</command>
   1.191 +to merge two changesets, but you haven't yet committed the results of
   1.192 +the merge, your working directory has two parents (use <command role="hg-cmd">hg parents</command>
   1.193 +to see them).  While <command role="hg-cmd">hg status</command> prints modifications relative to
   1.194 +<emphasis>both</emphasis> parents after an uncommitted merge, <command role="hg-cmd">hg diff</command> still
   1.195 +operates relative only to the first parent.  You can get it to print
   1.196 +diffs relative to the second parent by specifying that parent with the
   1.197 +<option role="hg-opt-diff">-r</option> option.  There is no way to print diffs relative to
   1.198 +both parents.
   1.199 +</para>
   1.200 +
   1.201 +</sect3>
   1.202 +<sect3>
   1.203 +<title>Generating safe binary diffs</title>
   1.204 +
   1.205 +<para>If you use the <option role="hg-opt-diff">-a</option> option to force Mercurial to print
   1.206 +diffs of files that are either <quote>mostly text</quote> or contain lots of
   1.207 +binary data, those diffs cannot subsequently be applied by either
   1.208 +Mercurial's <command role="hg-cmd">hg import</command> command or the system's <command>patch</command>
   1.209 +command.
   1.210 +</para>
   1.211 +
   1.212 +<para>If you want to generate a diff of a binary file that is safe to use as
   1.213 +input for <command role="hg-cmd">hg import</command>, use the <command role="hg-cmd">hg diff</command>{--git} option when you
   1.214 +generate the patch.  The system <command>patch</command> command cannot handle
   1.215 +binary patches at all.
   1.216 +</para>
   1.217 +
   1.218 +</sect3>
   1.219 +</sect2>
   1.220 +</appendix>
   1.221 +
   1.222 +<!--
   1.223 +local variables: 
   1.224 +sgml-parent-document: ("00book.xml" "book" "appendix")
   1.225 +end:
   1.226 +-->