Mercurial > hgbook
comparison en/appA-cmdref.xml @ 749:7e7c47481e4f
Oops, this is the real merge for my hg's oddity
author | Dongsheng Song <dongsheng.song@gmail.com> |
---|---|
date | Fri, 20 Mar 2009 16:43:35 +0800 |
parents | cfdb601a3c8b |
children | 1c13ed2130a7 |
comparison
equal
deleted
inserted
replaced
748:d13c7c706a58 | 749:7e7c47481e4f |
---|---|
1 <!-- vim: set filetype=docbkxml shiftwidth=2 autoindent expandtab tw=77 : --> | 1 <!-- vim: set filetype=docbkxml shiftwidth=2 autoindent expandtab tw=77 : --> |
2 | 2 |
3 <appendix id="cmdref"> | 3 <appendix id="cmdref"> |
4 <title>Command reference</title> | 4 <title>Command reference</title> |
5 | 5 |
6 <para>\cmdref{add}{add files at the next commit} | 6 <para id="x_653">\cmdref{add}{add files at the next commit} |
7 \optref{add}{I}{include} | 7 \optref{add}{I}{include} |
8 \optref{add}{X}{exclude} | 8 \optref{add}{X}{exclude} |
9 \optref{add}{n}{dry-run}</para> | 9 \optref{add}{n}{dry-run}</para> |
10 | 10 |
11 <para>\cmdref{diff}{print changes in history or working directory}</para> | 11 <para id="x_654">\cmdref{diff}{print changes in history or working directory}</para> |
12 | 12 |
13 <para>Show differences between revisions for the specified files or | 13 <para id="x_655">Show differences between revisions for the specified files or |
14 directories, using the unified diff format. For a description of the | 14 directories, using the unified diff format. For a description of the |
15 unified diff format, see section <xref linkend="sec.mq.patch"/>.</para> | 15 unified diff format, see section <xref linkend="sec.mq.patch"/>.</para> |
16 | 16 |
17 <para>By default, this command does not print diffs for files that Mercurial | 17 <para id="x_656">By default, this command does not print diffs for files that Mercurial |
18 considers to contain binary data. To control this behaviour, see the | 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> | 19 <option role="hg-opt-diff">-a</option> and <option role="hg-opt-diff">--git</option> options.</para> |
20 | 20 |
21 <sect2> | 21 <sect2> |
22 <title>Options</title> | 22 <title>Options</title> |
23 | 23 |
24 <para>\loptref{diff}{nodates}</para> | 24 <para id="x_657">\loptref{diff}{nodates}</para> |
25 | 25 |
26 <para>Omit date and time information when printing diff headers.</para> | 26 <para id="x_658">Omit date and time information when printing diff headers.</para> |
27 | 27 |
28 <para>\optref{diff}{B}{ignore-blank-lines}</para> | 28 <para id="x_659">\optref{diff}{B}{ignore-blank-lines}</para> |
29 | 29 |
30 <para>Do not print changes that only insert or delete blank lines. A line | 30 <para id="x_65a">Do not print changes that only insert or delete blank lines. A line |
31 that contains only whitespace is not considered blank. | 31 that contains only whitespace is not considered blank. |
32 </para> | 32 </para> |
33 | 33 |
34 <para>\optref{diff}{I}{include} | 34 <para id="x_65b">\optref{diff}{I}{include} |
35 </para> | 35 </para> |
36 | 36 |
37 <para>Include files and directories whose names match the given patterns. | 37 <para id="x_65c">Include files and directories whose names match the given patterns. |
38 </para> | 38 </para> |
39 | 39 |
40 <para>\optref{diff}{X}{exclude} | 40 <para id="x_65d">\optref{diff}{X}{exclude} |
41 </para> | 41 </para> |
42 | 42 |
43 <para>Exclude files and directories whose names match the given patterns. | 43 <para id="x_65e">Exclude files and directories whose names match the given patterns. |
44 </para> | 44 </para> |
45 | 45 |
46 <para>\optref{diff}{a}{text} | 46 <para id="x_65f">\optref{diff}{a}{text} |
47 </para> | 47 </para> |
48 | 48 |
49 <para>If this option is not specified, <command role="hg-cmd">hg diff</command> will refuse to print | 49 <para id="x_660">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> | 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 | 51 forces <command role="hg-cmd">hg diff</command> to treat all files as text, and generate diffs for |
52 all of them. | 52 all of them. |
53 </para> | 53 </para> |
54 | 54 |
55 <para>This option is useful for files that are <quote>mostly text</quote> but have a | 55 <para id="x_661">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 | 56 few embedded NUL characters. If you use it on files that contain a |
57 lot of binary data, its output will be incomprehensible. | 57 lot of binary data, its output will be incomprehensible. |
58 </para> | 58 </para> |
59 | 59 |
60 <para>\optref{diff}{b}{ignore-space-change} | 60 <para id="x_662">\optref{diff}{b}{ignore-space-change} |
61 </para> | 61 </para> |
62 | 62 |
63 <para>Do not print a line if the only change to that line is in the amount | 63 <para id="x_663">Do not print a line if the only change to that line is in the amount |
64 of white space it contains. | 64 of white space it contains. |
65 </para> | 65 </para> |
66 | 66 |
67 <para>\optref{diff}{g}{git} | 67 <para id="x_664">\optref{diff}{g}{git} |
68 </para> | 68 </para> |
69 | 69 |
70 <para>Print <command>git</command>-compatible diffs. XXX reference a format | 70 <para id="x_665">Print <command>git</command>-compatible diffs. XXX reference a format |
71 description. | 71 description. |
72 </para> | 72 </para> |
73 | 73 |
74 <para>\optref{diff}{p}{show-function} | 74 <para id="x_666">\optref{diff}{p}{show-function} |
75 </para> | 75 </para> |
76 | 76 |
77 <para>Display the name of the enclosing function in a hunk header, using a | 77 <para id="x_667">Display the name of the enclosing function in a hunk header, using a |
78 simple heuristic. This functionality is enabled by default, so the | 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 | 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> | 80 the <envar role="rc-item-diff">showfunc</envar> config item, as in the following example.</para> |
81 | 81 |
82 <!-- &interaction.cmdref.diff-p; --> | 82 <!-- &interaction.cmdref.diff-p; --> |
83 | 83 |
84 <para>\optref{diff}{r}{rev} | 84 <para id="x_668">\optref{diff}{r}{rev} |
85 </para> | 85 </para> |
86 | 86 |
87 <para>Specify one or more revisions to compare. The <command role="hg-cmd">hg diff</command> command | 87 <para id="x_669">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 | 88 accepts up to two <option role="hg-opt-diff">-r</option> options to specify the revisions to |
89 compare. | 89 compare. |
90 </para> | 90 </para> |
91 | 91 |
92 <orderedlist> | 92 <orderedlist> |
93 <listitem><para>Display the differences between the parent revision of the | 93 <listitem><para id="x_66a">Display the differences between the parent revision of the |
94 working directory and the working directory. | 94 working directory and the working directory. |
95 </para> | 95 </para> |
96 </listitem> | 96 </listitem> |
97 <listitem><para>Display the differences between the specified changeset and the | 97 <listitem><para id="x_66b">Display the differences between the specified changeset and the |
98 working directory. | 98 working directory. |
99 </para> | 99 </para> |
100 </listitem> | 100 </listitem> |
101 <listitem><para>Display the differences between the two specified changesets. | 101 <listitem><para id="x_66c">Display the differences between the two specified changesets. |
102 </para> | 102 </para> |
103 </listitem></orderedlist> | 103 </listitem></orderedlist> |
104 | 104 |
105 <para>You can specify two revisions using either two <option role="hg-opt-diff">-r</option> | 105 <para id="x_66d">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 | 106 options or revision range notation. For example, the two revision |
107 specifications below are equivalent. | 107 specifications below are equivalent. |
108 </para> | 108 </para> |
109 <programlisting>hg diff -r 10 -r 20 | 109 <programlisting>hg diff -r 10 -r 20 |
110 hg diff -r10:20</programlisting> | 110 hg diff -r10:20</programlisting> |
111 | 111 |
112 <para>When you provide two revisions, Mercurial treats the order of those | 112 <para id="x_66e">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 | 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 | 114 produce a diff that will transform files from their contents as of |
115 revision 10 to their contents as of revision 20, while | 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 | 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 | 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 | 118 contents. You cannot reverse the ordering in this way if you are |
119 diffing against the working directory. | 119 diffing against the working directory. |
120 </para> | 120 </para> |
121 | 121 |
122 <para>\optref{diff}{w}{ignore-all-space} | 122 <para id="x_66f">\optref{diff}{w}{ignore-all-space} |
123 </para> | 123 </para> |
124 | 124 |
125 <para>\cmdref{version}{print version and copyright information} | 125 <para id="x_670">\cmdref{version}{print version and copyright information} |
126 </para> | 126 </para> |
127 | 127 |
128 <para>This command displays the version of Mercurial you are running, and | 128 <para id="x_671">This command displays the version of Mercurial you are running, and |
129 its copyright license. There are four kinds of version string that | 129 its copyright license. There are four kinds of version string that |
130 you may see. | 130 you may see. |
131 </para> | 131 </para> |
132 <itemizedlist> | 132 <itemizedlist> |
133 <listitem><para>The string <quote><literal>unknown</literal></quote>. This version of Mercurial was | 133 <listitem><para id="x_672">The string <quote><literal>unknown</literal></quote>. This version of Mercurial was |
134 not built in a Mercurial repository, and cannot determine its own | 134 not built in a Mercurial repository, and cannot determine its own |
135 version. | 135 version. |
136 </para> | 136 </para> |
137 </listitem> | 137 </listitem> |
138 <listitem><para>A short numeric string, such as <quote><literal>1.1</literal></quote>. This is a | 138 <listitem><para id="x_673">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 | 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 | 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 | 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 | 142 have added that tag to any revision in the repository where they |
143 built Mercurial.) | 143 built Mercurial.) |
144 </para> | 144 </para> |
145 </listitem> | 145 </listitem> |
146 <listitem><para>A hexadecimal string, such as <quote><literal>875489e31abe</literal></quote>. This | 146 <listitem><para id="x_674">A hexadecimal string, such as <quote><literal>875489e31abe</literal></quote>. This |
147 is a build of the given revision of Mercurial. | 147 is a build of the given revision of Mercurial. |
148 </para> | 148 </para> |
149 </listitem> | 149 </listitem> |
150 <listitem><para>A hexadecimal string followed by a date, such as | 150 <listitem><para id="x_675">A hexadecimal string followed by a date, such as |
151 <quote><literal>875489e31abe+20070205</literal></quote>. This is a build of the given | 151 <quote><literal>875489e31abe+20070205</literal></quote>. This is a build of the given |
152 revision of Mercurial, where the build repository contained some | 152 revision of Mercurial, where the build repository contained some |
153 local changes that had not been committed. | 153 local changes that had not been committed. |
154 </para> | 154 </para> |
155 </listitem></itemizedlist> | 155 </listitem></itemizedlist> |
159 <title>Tips and tricks</title> | 159 <title>Tips and tricks</title> |
160 | 160 |
161 <sect3 id="cmdref.diff-vs-status"> | 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> | 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 | 163 |
164 <para>When you run the <command role="hg-cmd">hg status</command> command, you'll see a list of files | 164 <para id="x_676">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 | 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 | 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> | 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. | 168 listed. There are two possible reasons for this. |
169 </para> | 169 </para> |
170 | 170 |
171 <para>The first is that <command role="hg-cmd">hg status</command> prints some kinds of modifications | 171 <para id="x_677">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 | 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 | 173 normally outputs unified diffs, which don't have the ability to |
174 represent some changes that Mercurial can track. Most notably, | 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 | 175 traditional diffs can't represent a change in whether or not a file is |
176 executable, but Mercurial records this information. | 176 executable, but Mercurial records this information. |
177 </para> | 177 </para> |
178 | 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 | 179 <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 |
180 display <command>git</command>-compatible diffs that <emphasis>can</emphasis> display this | 180 display <command>git</command>-compatible diffs that <emphasis>can</emphasis> display this |
181 extra information. | 181 extra information. |
182 </para> | 182 </para> |
183 | 183 |
184 <para>The second possible reason that <command role="hg-cmd">hg diff</command> might be printing diffs | 184 <para id="x_679">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 | 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 | 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> | 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 | 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> | 189 the merge, your working directory has two parents (use <command role="hg-cmd">hg parents</command> |
197 | 197 |
198 </sect3> | 198 </sect3> |
199 <sect3> | 199 <sect3> |
200 <title>Generating safe binary diffs</title> | 200 <title>Generating safe binary diffs</title> |
201 | 201 |
202 <para>If you use the <option role="hg-opt-diff">-a</option> option to force Mercurial to print | 202 <para id="x_67a">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 | 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 | 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> | 205 Mercurial's <command role="hg-cmd">hg import</command> command or the system's <command>patch</command> |
206 command. | 206 command. |
207 </para> | 207 </para> |
208 | 208 |
209 <para>If you want to generate a diff of a binary file that is safe to use as | 209 <para id="x_67b">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 | 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 | 211 generate the patch. The system <command>patch</command> command cannot handle |
212 binary patches at all. | 212 binary patches at all. |
213 </para> | 213 </para> |
214 | 214 |