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