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