hgbook
view en/appA-cmdref.xml @ 676:29f0f79cf614
Update paragraph IDs
| author | Bryan O'Sullivan <bos@serpentine.com> |
|---|---|
| date | Thu Apr 16 23:46:45 2009 -0700 (2009-04-16) |
| parents | 1c13ed2130a7 |
| children |
line source
1 <!-- vim: set filetype=docbkxml shiftwidth=2 autoindent expandtab tw=77 : -->
3 <appendix id="cmdref">
4 <?dbhtml filename="command-reference.html"?>
5 <title>Command reference</title>
7 <para id="x_653">\cmdref{add}{add files at the next commit}
8 \optref{add}{I}{include}
9 \optref{add}{X}{exclude}
10 \optref{add}{n}{dry-run}</para>
12 <para id="x_654">\cmdref{diff}{print changes in history or working directory}</para>
14 <para id="x_655">Show differences between revisions for the specified files or
15 directories, using the unified diff format. For a description of the
16 unified diff format, see <xref linkend="sec:mq:patch"/>.</para>
18 <para id="x_656">By default, this command does not print diffs for files that Mercurial
19 considers to contain binary data. To control this behavior, see the
20 <option role="hg-opt-diff">-a</option> and <option role="hg-opt-diff">--git</option> options.</para>
22 <sect2>
23 <title>Options</title>
24 x
25 <para id="x_657">\loptref{diff}{nodates}</para>
27 <para id="x_658">Omit date and time information when printing diff headers.</para>
29 <para id="x_659">\optref{diff}{B}{ignore-blank-lines}</para>
31 <para id="x_65a">Do not print changes that only insert or delete blank lines. A line
32 that contains only whitespace is not considered blank.
33 </para>
35 <para id="x_65b">\optref{diff}{I}{include}
36 </para>
38 <para id="x_65c">Include files and directories whose names match the given patterns.
39 </para>
41 <para id="x_65d">\optref{diff}{X}{exclude}
42 </para>
44 <para id="x_65e">Exclude files and directories whose names match the given patterns.
45 </para>
47 <para id="x_65f">\optref{diff}{a}{text}
48 </para>
50 <para id="x_660">If this option is not specified, <command role="hg-cmd">hg diff</command> will refuse to print
51 diffs for files that it detects as binary. Specifying <option role="hg-opt-diff">-a</option>
52 forces <command role="hg-cmd">hg diff</command> to treat all files as text, and generate diffs for
53 all of them.
54 </para>
56 <para id="x_661">This option is useful for files that are <quote>mostly text</quote> but have a
57 few embedded NUL characters. If you use it on files that contain a
58 lot of binary data, its output will be incomprehensible.
59 </para>
61 <para id="x_662">\optref{diff}{b}{ignore-space-change}
62 </para>
64 <para id="x_663">Do not print a line if the only change to that line is in the amount
65 of white space it contains.
66 </para>
68 <para id="x_664">\optref{diff}{g}{git}
69 </para>
71 <para id="x_665">Print <command>git</command>-compatible diffs. XXX reference a format
72 description.
73 </para>
75 <para id="x_666">\optref{diff}{p}{show-function}
76 </para>
78 <para id="x_667">Display the name of the enclosing function in a hunk header, using a
79 simple heuristic. This functionality is enabled by default, so the
80 <option role="hg-opt-diff">-p</option> option has no effect unless you change the value of
81 the <envar role="rc-item-diff">showfunc</envar> config item, as in the following example.</para>
83 <!-- &interaction.cmdref.diff-p; -->
85 <para id="x_668">\optref{diff}{r}{rev}
86 </para>
88 <para id="x_669">Specify one or more revisions to compare. The <command role="hg-cmd">hg diff</command> command
89 accepts up to two <option role="hg-opt-diff">-r</option> options to specify the revisions to
90 compare.
91 </para>
93 <orderedlist>
94 <listitem><para id="x_66a">Display the differences between the parent revision of the
95 working directory and the working directory.
96 </para>
97 </listitem>
98 <listitem><para id="x_66b">Display the differences between the specified changeset and the
99 working directory.
100 </para>
101 </listitem>
102 <listitem><para id="x_66c">Display the differences between the two specified changesets.
103 </para>
104 </listitem></orderedlist>
106 <para id="x_66d">You can specify two revisions using either two <option role="hg-opt-diff">-r</option>
107 options or revision range notation. For example, the two revision
108 specifications below are equivalent.
109 </para>
110 <programlisting>hg diff -r 10 -r 20
111 hg diff -r10:20</programlisting>
113 <para id="x_66e">When you provide two revisions, Mercurial treats the order of those
114 revisions as significant. Thus, <command role="hg-cmd">hg diff -r10:20</command> will
115 produce a diff that will transform files from their contents as of
116 revision 10 to their contents as of revision 20, while
117 <command role="hg-cmd">hg diff -r20:10</command> means the opposite: the diff that will
118 transform files from their revision 20 contents to their revision 10
119 contents. You cannot reverse the ordering in this way if you are
120 diffing against the working directory.
121 </para>
123 <para id="x_66f">\optref{diff}{w}{ignore-all-space}
124 </para>
126 <para id="x_670">\cmdref{version}{print version and copyright information}
127 </para>
129 <para id="x_671">This command displays the version of Mercurial you are running, and
130 its copyright license. There are four kinds of version string that
131 you may see.
132 </para>
133 <itemizedlist>
134 <listitem><para id="x_672">The string <quote><literal>unknown</literal></quote>. This version of Mercurial was
135 not built in a Mercurial repository, and cannot determine its own
136 version.
137 </para>
138 </listitem>
139 <listitem><para id="x_673">A short numeric string, such as <quote><literal>1.1</literal></quote>. This is a
140 build of a revision of Mercurial that was identified by a specific
141 tag in the repository where it was built. (This doesn't necessarily
142 mean that you're running an official release; someone else could
143 have added that tag to any revision in the repository where they
144 built Mercurial.)
145 </para>
146 </listitem>
147 <listitem><para id="x_674">A hexadecimal string, such as <quote><literal>875489e31abe</literal></quote>. This
148 is a build of the given revision of Mercurial.
149 </para>
150 </listitem>
151 <listitem><para id="x_675">A hexadecimal string followed by a date, such as
152 <quote><literal>875489e31abe+20070205</literal></quote>. This is a build of the given
153 revision of Mercurial, where the build repository contained some
154 local changes that had not been committed.
155 </para>
156 </listitem></itemizedlist>
158 </sect2>
159 <sect2>
160 <title>Tips and tricks</title>
162 <sect3 id="cmdref:diff-vs-status">
163 <title>Why do the results of <command role="hg-cmd">hg diff</command> and <command role="hg-cmd">hg status</command> differ?</title>
165 <para id="x_676">When you run the <command role="hg-cmd">hg status</command> command, you'll see a list of files
166 that Mercurial will record changes for the next time you perform a
167 commit. If you run the <command role="hg-cmd">hg diff</command> command, you may notice that it
168 prints diffs for only a <emphasis>subset</emphasis> of the files that <command role="hg-cmd">hg status</command>
169 listed. There are two possible reasons for this.
170 </para>
172 <para id="x_677">The first is that <command role="hg-cmd">hg status</command> prints some kinds of modifications
173 that <command role="hg-cmd">hg diff</command> doesn't normally display. The <command role="hg-cmd">hg diff</command> command
174 normally outputs unified diffs, which don't have the ability to
175 represent some changes that Mercurial can track. Most notably,
176 traditional diffs can't represent a change in whether or not a file is
177 executable, but Mercurial records this information.
178 </para>
180 <para id="x_678">If you use the <option role="hg-opt-diff">--git</option> option to <command role="hg-cmd">hg diff</command>, it will
181 display <command>git</command>-compatible diffs that <emphasis>can</emphasis> display this
182 extra information.
183 </para>
185 <para id="x_679">The second possible reason that <command role="hg-cmd">hg diff</command> might be printing diffs
186 for a subset of the files displayed by <command role="hg-cmd">hg status</command> is that if you
187 invoke it without any arguments, <command role="hg-cmd">hg diff</command> prints diffs against the
188 first parent of the working directory. If you have run <command role="hg-cmd">hg merge</command>
189 to merge two changesets, but you haven't yet committed the results of
190 the merge, your working directory has two parents (use <command role="hg-cmd">hg parents</command>
191 to see them). While <command role="hg-cmd">hg status</command> prints modifications relative to
192 <emphasis>both</emphasis> parents after an uncommitted merge, <command role="hg-cmd">hg diff</command> still
193 operates relative only to the first parent. You can get it to print
194 diffs relative to the second parent by specifying that parent with the
195 <option role="hg-opt-diff">-r</option> option. There is no way to print diffs relative to
196 both parents.
197 </para>
199 </sect3>
200 <sect3>
201 <title>Generating safe binary diffs</title>
203 <para id="x_67a">If you use the <option role="hg-opt-diff">-a</option> option to force Mercurial to print
204 diffs of files that are either <quote>mostly text</quote> or contain lots of
205 binary data, those diffs cannot subsequently be applied by either
206 Mercurial's <command role="hg-cmd">hg import</command> command or the system's <command>patch</command>
207 command.
208 </para>
210 <para id="x_67b">If you want to generate a diff of a binary file that is safe to use as
211 input for <command role="hg-cmd">hg import</command>, use the <command role="hg-cmd">hg diff</command>{--git} option when you
212 generate the patch. The system <command>patch</command> command cannot handle
213 binary patches at all.
214 </para>
216 </sect3>
217 </sect2>
218 </appendix>
220 <!--
221 local variables:
222 sgml-parent-document: ("00book.xml" "book" "appendix")
223 end:
224 -->