Mercurial > hgbook
diff en/appA-cmdref.xml @ 658:b90b024729f1
WIP DocBook snapshot that all compiles. Mirabile dictu!
author | Bryan O'Sullivan <bos@serpentine.com> |
---|---|
date | Wed, 18 Feb 2009 00:22:09 -0800 |
parents | en/appA-cmdref.tex@f72b7e6cbe90 |
children | c838b3975bc6 cfdb601a3c8b |
line wrap: on
line diff
--- /dev/null Thu Jan 01 00:00:00 1970 +0000 +++ b/en/appA-cmdref.xml Wed Feb 18 00:22:09 2009 -0800 @@ -0,0 +1,223 @@ +<!-- 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: +-->