| rev |
line source |
|
bos@132
|
1 \chapter{Command reference}
|
|
bos@132
|
2 \label{cmdref}
|
|
bos@132
|
3
|
|
bos@132
|
4 \cmdref{diff}
|
|
bos@132
|
5
|
|
bos@132
|
6 Show differences between revisions for the specified files or
|
|
bos@132
|
7 directories, using the unified diff format. For a description of the
|
|
bos@132
|
8 unified diff format, see section~\ref{sec:mq:patch}.
|
|
bos@132
|
9
|
|
bos@132
|
10 \optref{diff}{-r}{--rev}
|
|
bos@132
|
11
|
|
bos@132
|
12 Specify a revision to compare.
|
|
bos@132
|
13
|
|
bos@132
|
14 \optref{diff}{-a}{--text}
|
|
bos@132
|
15
|
|
bos@132
|
16 If this option is not specified, \hgcmd{diff} will refuse to print
|
|
bos@132
|
17 diffs for files that it detects as binary. Specifying \hgopt{diff}{-a}
|
|
bos@132
|
18 forces \hgcmd{diff} to treat all files as text, and generate diffs for
|
|
bos@132
|
19 all of them.
|
|
bos@132
|
20
|
|
bos@132
|
21 This option is useful for files that are ``mostly text'' but have a
|
|
bos@132
|
22 few embedded NUL characters. If you use it on files that are really
|
|
bos@132
|
23 binary, its output will be incomprehensible.
|
|
bos@132
|
24
|
|
bos@132
|
25 \subsection{Specifying revisions}
|
|
bos@132
|
26
|
|
bos@132
|
27 The \hgcmd{diff} command accepts up to two \hgopt{diff}{-r} options to
|
|
bos@132
|
28 specify the revisions to compare.
|
|
bos@132
|
29
|
|
bos@132
|
30 \begin{enumerate}
|
|
bos@132
|
31 \setcounter{enumi}{0}
|
|
bos@132
|
32 \item Display the differences between the parent of the working
|
|
bos@132
|
33 directory and the working directory.
|
|
bos@132
|
34 \item Display the differences between the specified changeset and the
|
|
bos@132
|
35 working directory.
|
|
bos@132
|
36 \item Display the differences between the two specified changesets.
|
|
bos@132
|
37 \end{enumerate}
|
|
bos@132
|
38
|
|
bos@132
|
39 You can specify two revisions using either two \hgopt{diff}{-r}
|
|
bos@132
|
40 options or revision range notation. For example, the two revision
|
|
bos@132
|
41 specifications below are equivalent.
|
|
bos@132
|
42 \begin{codesample2}
|
|
bos@132
|
43 hg diff -r 10 -r 20
|
|
bos@132
|
44 hg diff -r10:20
|
|
bos@132
|
45 \end{codesample2}
|
|
bos@132
|
46
|
|
bos@132
|
47 When you provide two revisions, Mercurial treats the order of those
|
|
bos@132
|
48 revisions as significant. Thus, \hgcmdargs{diff}{-r10:20} will
|
|
bos@132
|
49 produce a diff that will transform files from their contents as of
|
|
bos@132
|
50 revision~10 to their contents as of revision~20, while
|
|
bos@132
|
51 \hgcmdargs{diff}{-r20:10} means the opposite: the diff that will
|
|
bos@132
|
52 transform files from their revision~20 contents to their revision~10
|
|
bos@132
|
53 contents. You cannot reverse the ordering in this way if you are
|
|
bos@132
|
54 diffing against the working directory.
|
|
bos@132
|
55
|
|
bos@132
|
56 \subsection{Why do the results of \hgcmd{diff} and \hgcmd{status}
|
|
bos@132
|
57 differ?}
|
|
bos@132
|
58 \label{cmdref:diff-vs-status}
|
|
bos@132
|
59
|
|
bos@132
|
60 When you run the \hgcmd{status} command, you'll see a list of files
|
|
bos@132
|
61 that Mercurial will record changes for the next time you perform a
|
|
bos@132
|
62 commit. If you run the \hgcmd{diff} command, you may notice that it
|
|
bos@132
|
63 prints diffs for only a \emph{subset} of the files that \hgcmd{status}
|
|
bos@132
|
64 listed. There are two possible reasons for this.
|
|
bos@132
|
65
|
|
bos@132
|
66 The first is that \hgcmd{status} prints some kinds of modifications
|
|
bos@132
|
67 that \hgcmd{diff} doesn't normally display. The \hgcmd{diff} command
|
|
bos@132
|
68 normally outputs unified diffs, which don't have the ability to
|
|
bos@132
|
69 represent some changes that Mercurial can track. Most notably,
|
|
bos@132
|
70 traditional diffs can't represent a change in whether or not a file is
|
|
bos@132
|
71 executable, but Mercurial records this information.
|
|
bos@132
|
72
|
|
bos@132
|
73 If you use the \hgopt{diff}{--git} option to \hgcmd{diff}, it will
|
|
bos@132
|
74 display \command{git}-compatible diffs that \emph{can} display this
|
|
bos@132
|
75 extra information.
|
|
bos@132
|
76
|
|
bos@132
|
77 The second possible reason that \hgcmd{diff} might be printing diffs
|
|
bos@132
|
78 for a subset of the files displayed by \hgcmd{status} is that if you
|
|
bos@132
|
79 invoke it without any arguments, \hgcmd{diff} prints diffs against the
|
|
bos@132
|
80 first parent of the working directory. If you have run \hgcmd{merge}
|
|
bos@132
|
81 to merge two changesets, but you haven't yet committed the results of
|
|
bos@132
|
82 the merge, your working directory has two parents (use \hgcmd{parents}
|
|
bos@132
|
83 to see them). While \hgcmd{status} prints modifications relative to
|
|
bos@132
|
84 \emph{both} parents after an uncommitted merge, \hgcmd{diff} still
|
|
bos@132
|
85 operates relative only to the first parent. You can get it to print
|
|
bos@132
|
86 diffs relative to the second parent by specifying that parent with the
|
|
bos@132
|
87 \hgopt{diff}{-r} option. There is no way to print diffs relative to
|
|
bos@132
|
88 both parents.
|
|
bos@132
|
89
|
|
bos@132
|
90 \subsection{Generating safe binary diffs}
|
|
bos@132
|
91
|
|
bos@132
|
92 If you use the \hgopt{diff}{-a} option to force Mercurial to print
|
|
bos@132
|
93 diffs of files that are either ``mostly text'' or contain lots of
|
|
bos@132
|
94 binary data, those diffs cannot subsequently be applied by either
|
|
bos@132
|
95 Mercurial's \hgcmd{import} command or the system's \command{patch}
|
|
bos@132
|
96 command.
|
|
bos@132
|
97
|
|
bos@132
|
98 If you want to generate a diff of a binary file that is safe to use as
|
|
bos@132
|
99 input for \hgcmd{import}, use the \hgcmd{diff}{--git} option when you
|
|
bos@132
|
100 generate the patch. The system \command{patch} command cannot handle
|
|
bos@132
|
101 binary patches at all.
|
|
bos@132
|
102
|
|
bos@132
|
103 %%% Local Variables:
|
|
bos@132
|
104 %%% mode: latex
|
|
bos@132
|
105 %%% TeX-master: "00book"
|
|
bos@132
|
106 %%% End:
|
