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