hgbook
changeset 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 | 153efeaa8f57 |
children | 1e013fbe35f7 |
files | en/00book.tex en/99defs.tex en/Makefile en/cmdref.tex |
line diff
1.1 --- a/en/00book.tex Thu Dec 28 14:10:23 2006 -0800 1.2 +++ b/en/00book.tex Thu Dec 28 16:45:56 2006 -0800 1.3 @@ -46,9 +46,10 @@ 1.4 \include{template} 1.5 \include{mq} 1.6 \include{mq-collab} 1.7 -\include{mq-ref} 1.8 1.9 \appendix 1.10 +\include{cmdref} 1.11 +\include{mq-ref} 1.12 \include{srcinstall} 1.13 \include{license} 1.14 \addcontentsline{toc}{chapter}{Bibliography}
2.1 --- a/en/99defs.tex Thu Dec 28 14:10:23 2006 -0800 2.2 +++ b/en/99defs.tex Thu Dec 28 16:45:56 2006 -0800 2.3 @@ -116,6 +116,12 @@ 2.4 \newcommand{\grafix}[1]{\includegraphics{#1.png}} 2.5 \fi 2.6 2.7 +% Reference entry for a command. 2.8 +\newcommand{\cmdref}[1]{\section{#1}\label{cmdref:#1}\index{\texttt{#1} command}``\texttt{hg #1}''} 2.9 + 2.10 +% Reference entry for a command option. 2.11 +\newcommand{\optref}[2]{\index{\texttt{#1} command!\texttt{#2} option}\texttt{#2}} 2.12 + 2.13 %%% Local Variables: 2.14 %%% mode: latex 2.15 %%% TeX-master: "00book"
3.1 --- a/en/Makefile Thu Dec 28 14:10:23 2006 -0800 3.2 +++ b/en/Makefile Thu Dec 28 16:45:56 2006 -0800 3.3 @@ -7,6 +7,7 @@ 3.4 99book.bib \ 3.5 99defs.tex \ 3.6 build_id.tex \ 3.7 + cmdref.tex \ 3.8 concepts.tex \ 3.9 daily.tex \ 3.10 hook.tex \
4.1 --- /dev/null Thu Jan 01 00:00:00 1970 +0000 4.2 +++ b/en/cmdref.tex Thu Dec 28 16:45:56 2006 -0800 4.3 @@ -0,0 +1,106 @@ 4.4 +\chapter{Command reference} 4.5 +\label{cmdref} 4.6 + 4.7 +\cmdref{diff} 4.8 + 4.9 +Show differences between revisions for the specified files or 4.10 +directories, using the unified diff format. For a description of the 4.11 +unified diff format, see section~\ref{sec:mq:patch}. 4.12 + 4.13 +\optref{diff}{-r}{--rev} 4.14 + 4.15 +Specify a revision to compare. 4.16 + 4.17 +\optref{diff}{-a}{--text} 4.18 + 4.19 +If this option is not specified, \hgcmd{diff} will refuse to print 4.20 +diffs for files that it detects as binary. Specifying \hgopt{diff}{-a} 4.21 +forces \hgcmd{diff} to treat all files as text, and generate diffs for 4.22 +all of them. 4.23 + 4.24 +This option is useful for files that are ``mostly text'' but have a 4.25 +few embedded NUL characters. If you use it on files that are really 4.26 +binary, its output will be incomprehensible. 4.27 + 4.28 +\subsection{Specifying revisions} 4.29 + 4.30 +The \hgcmd{diff} command accepts up to two \hgopt{diff}{-r} options to 4.31 +specify the revisions to compare. 4.32 + 4.33 +\begin{enumerate} 4.34 +\setcounter{enumi}{0} 4.35 +\item Display the differences between the parent of the working 4.36 + directory and the working directory. 4.37 +\item Display the differences between the specified changeset and the 4.38 + working directory. 4.39 +\item Display the differences between the two specified changesets. 4.40 +\end{enumerate} 4.41 + 4.42 +You can specify two revisions using either two \hgopt{diff}{-r} 4.43 +options or revision range notation. For example, the two revision 4.44 +specifications below are equivalent. 4.45 +\begin{codesample2} 4.46 + hg diff -r 10 -r 20 4.47 + hg diff -r10:20 4.48 +\end{codesample2} 4.49 + 4.50 +When you provide two revisions, Mercurial treats the order of those 4.51 +revisions as significant. Thus, \hgcmdargs{diff}{-r10:20} will 4.52 +produce a diff that will transform files from their contents as of 4.53 +revision~10 to their contents as of revision~20, while 4.54 +\hgcmdargs{diff}{-r20:10} means the opposite: the diff that will 4.55 +transform files from their revision~20 contents to their revision~10 4.56 +contents. You cannot reverse the ordering in this way if you are 4.57 +diffing against the working directory. 4.58 + 4.59 +\subsection{Why do the results of \hgcmd{diff} and \hgcmd{status} 4.60 + differ?} 4.61 +\label{cmdref:diff-vs-status} 4.62 + 4.63 +When you run the \hgcmd{status} command, you'll see a list of files 4.64 +that Mercurial will record changes for the next time you perform a 4.65 +commit. If you run the \hgcmd{diff} command, you may notice that it 4.66 +prints diffs for only a \emph{subset} of the files that \hgcmd{status} 4.67 +listed. There are two possible reasons for this. 4.68 + 4.69 +The first is that \hgcmd{status} prints some kinds of modifications 4.70 +that \hgcmd{diff} doesn't normally display. The \hgcmd{diff} command 4.71 +normally outputs unified diffs, which don't have the ability to 4.72 +represent some changes that Mercurial can track. Most notably, 4.73 +traditional diffs can't represent a change in whether or not a file is 4.74 +executable, but Mercurial records this information. 4.75 + 4.76 +If you use the \hgopt{diff}{--git} option to \hgcmd{diff}, it will 4.77 +display \command{git}-compatible diffs that \emph{can} display this 4.78 +extra information. 4.79 + 4.80 +The second possible reason that \hgcmd{diff} might be printing diffs 4.81 +for a subset of the files displayed by \hgcmd{status} is that if you 4.82 +invoke it without any arguments, \hgcmd{diff} prints diffs against the 4.83 +first parent of the working directory. If you have run \hgcmd{merge} 4.84 +to merge two changesets, but you haven't yet committed the results of 4.85 +the merge, your working directory has two parents (use \hgcmd{parents} 4.86 +to see them). While \hgcmd{status} prints modifications relative to 4.87 +\emph{both} parents after an uncommitted merge, \hgcmd{diff} still 4.88 +operates relative only to the first parent. You can get it to print 4.89 +diffs relative to the second parent by specifying that parent with the 4.90 +\hgopt{diff}{-r} option. There is no way to print diffs relative to 4.91 +both parents. 4.92 + 4.93 +\subsection{Generating safe binary diffs} 4.94 + 4.95 +If you use the \hgopt{diff}{-a} option to force Mercurial to print 4.96 +diffs of files that are either ``mostly text'' or contain lots of 4.97 +binary data, those diffs cannot subsequently be applied by either 4.98 +Mercurial's \hgcmd{import} command or the system's \command{patch} 4.99 +command. 4.100 + 4.101 +If you want to generate a diff of a binary file that is safe to use as 4.102 +input for \hgcmd{import}, use the \hgcmd{diff}{--git} option when you 4.103 +generate the patch. The system \command{patch} command cannot handle 4.104 +binary patches at all. 4.105 + 4.106 +%%% Local Variables: 4.107 +%%% mode: latex 4.108 +%%% TeX-master: "00book" 4.109 +%%% End: