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