hgbook

annotate en/cmdref.tex @ 171:8c1703a98266

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