bos@132: \chapter{Command reference} bos@132: \label{cmdref} bos@132: bos@133: \cmdref{add}{add files at the next commit} bos@133: \optref{add}{I}{include} bos@133: \optref{add}{X}{exclude} bos@133: \optref{add}{n}{dry-run} bos@133: bos@133: \cmdref{diff}{print changes in history or working directory} bos@132: bos@132: Show differences between revisions for the specified files or bos@132: directories, using the unified diff format. For a description of the bos@132: unified diff format, see section~\ref{sec:mq:patch}. bos@132: bos@133: By default, this command does not print diffs for files that Mercurial bos@133: considers to contain binary data. To control this behaviour, see the bos@133: \hgopt{diff}{-a} and \hgopt{diff}{--git} options. bos@132: bos@133: \subsection{Options} bos@132: bos@133: \loptref{diff}{nodates} bos@133: bos@133: Omit date and time information when printing diff headers. bos@133: bos@133: \optref{diff}{B}{ignore-blank-lines} bos@133: bos@133: Do not print changes that only insert or delete blank lines. A line bos@133: that contains only whitespace is not considered blank. bos@133: bos@133: \optref{diff}{I}{include} bos@133: bos@133: Exclude files and directories whose names match the given patterns. bos@133: bos@133: \optref{diff}{X}{exclude} bos@133: bos@133: Include files and directories whose names match the given patterns. bos@133: bos@133: \optref{diff}{a}{text} bos@132: bos@132: If this option is not specified, \hgcmd{diff} will refuse to print bos@132: diffs for files that it detects as binary. Specifying \hgopt{diff}{-a} bos@132: forces \hgcmd{diff} to treat all files as text, and generate diffs for bos@132: all of them. bos@132: bos@132: This option is useful for files that are ``mostly text'' but have a bos@133: few embedded NUL characters. If you use it on files that contain a bos@133: lot of binary data, its output will be incomprehensible. bos@132: bos@133: \optref{diff}{b}{ignore-space-change} bos@132: bos@133: Do not print a line if the only change to that line is in the amount bos@133: of white space it contains. bos@133: bos@133: \optref{diff}{g}{git} bos@133: bos@133: Print \command{git}-compatible diffs. XXX reference a format bos@133: description. bos@133: bos@133: \optref{diff}{p}{show-function} bos@133: bos@133: Display the name of the enclosing function in a hunk header, using a bos@133: simple heuristic. This functionality is enabled by default, so the bos@133: \hgopt{diff}{-p} option has no effect unless you change the value of bos@133: the \rcitem{diff}{showfunc} config item, as in the following example. bos@133: \interaction{cmdref.diff-p} bos@133: bos@133: \optref{diff}{r}{rev} bos@133: bos@133: Specify one or more revisions to compare. The \hgcmd{diff} command bos@133: accepts up to two \hgopt{diff}{-r} options to specify the revisions to bos@133: compare. bos@132: bos@132: \begin{enumerate} bos@132: \setcounter{enumi}{0} bos@133: \item Display the differences between the parent revision of the bos@133: working directory and the working directory. bos@132: \item Display the differences between the specified changeset and the bos@132: working directory. bos@132: \item Display the differences between the two specified changesets. bos@132: \end{enumerate} bos@132: bos@132: You can specify two revisions using either two \hgopt{diff}{-r} bos@132: options or revision range notation. For example, the two revision bos@132: specifications below are equivalent. bos@132: \begin{codesample2} bos@132: hg diff -r 10 -r 20 bos@132: hg diff -r10:20 bos@132: \end{codesample2} bos@132: bos@132: When you provide two revisions, Mercurial treats the order of those bos@132: revisions as significant. Thus, \hgcmdargs{diff}{-r10:20} will bos@132: produce a diff that will transform files from their contents as of bos@132: revision~10 to their contents as of revision~20, while bos@132: \hgcmdargs{diff}{-r20:10} means the opposite: the diff that will bos@132: transform files from their revision~20 contents to their revision~10 bos@132: contents. You cannot reverse the ordering in this way if you are bos@132: diffing against the working directory. bos@132: bos@133: \optref{diff}{w}{ignore-all-space} bos@133: bos@133: \cmdref{version}{print version and copyright information} bos@133: bos@133: This command displays the version of Mercurial you are running, and bos@133: its copyright license. There are four kinds of version string that bos@133: you may see. bos@133: \begin{itemize} bos@133: \item The string ``\texttt{unknown}''. This version of Mercurial was bos@133: not built in a Mercurial repository, and cannot determine its own bos@133: version. bos@133: \item A short numeric string, such as ``\texttt{1.1}''. This is a bos@133: build of a revision of Mercurial that was identified by a specific bos@133: tag in the repository where it was built. (This doesn't necessarily bos@133: mean that you're running an official release; someone else could bos@133: have added that tag to any revision in the repository where they bos@133: built Mercurial.) bos@133: \item A hexadecimal string, such as ``\texttt{875489e31abe}''. This bos@133: is a build of the given revision of Mercurial. bos@133: \item A hexadecimal string followed by a date, such as bos@133: ``\texttt{875489e31abe+20070205}''. This is a build of the given bos@133: revision of Mercurial, where the build repository contained some bos@133: local changes that had not been committed. bos@133: \end{itemize} bos@133: bos@133: \subsection{Tips and tricks} bos@133: bos@133: \subsubsection{Why do the results of \hgcmd{diff} and \hgcmd{status} bos@132: differ?} bos@132: \label{cmdref:diff-vs-status} bos@132: bos@132: When you run the \hgcmd{status} command, you'll see a list of files bos@132: that Mercurial will record changes for the next time you perform a bos@132: commit. If you run the \hgcmd{diff} command, you may notice that it bos@132: prints diffs for only a \emph{subset} of the files that \hgcmd{status} bos@132: listed. There are two possible reasons for this. bos@132: bos@132: The first is that \hgcmd{status} prints some kinds of modifications bos@132: that \hgcmd{diff} doesn't normally display. The \hgcmd{diff} command bos@132: normally outputs unified diffs, which don't have the ability to bos@132: represent some changes that Mercurial can track. Most notably, bos@132: traditional diffs can't represent a change in whether or not a file is bos@132: executable, but Mercurial records this information. bos@132: bos@132: If you use the \hgopt{diff}{--git} option to \hgcmd{diff}, it will bos@132: display \command{git}-compatible diffs that \emph{can} display this bos@132: extra information. bos@132: bos@132: The second possible reason that \hgcmd{diff} might be printing diffs bos@132: for a subset of the files displayed by \hgcmd{status} is that if you bos@132: invoke it without any arguments, \hgcmd{diff} prints diffs against the bos@132: first parent of the working directory. If you have run \hgcmd{merge} bos@132: to merge two changesets, but you haven't yet committed the results of bos@132: the merge, your working directory has two parents (use \hgcmd{parents} bos@132: to see them). While \hgcmd{status} prints modifications relative to bos@132: \emph{both} parents after an uncommitted merge, \hgcmd{diff} still bos@132: operates relative only to the first parent. You can get it to print bos@132: diffs relative to the second parent by specifying that parent with the bos@132: \hgopt{diff}{-r} option. There is no way to print diffs relative to bos@132: both parents. bos@132: bos@133: \subsubsection{Generating safe binary diffs} bos@132: bos@132: If you use the \hgopt{diff}{-a} option to force Mercurial to print bos@132: diffs of files that are either ``mostly text'' or contain lots of bos@132: binary data, those diffs cannot subsequently be applied by either bos@132: Mercurial's \hgcmd{import} command or the system's \command{patch} bos@132: command. bos@132: bos@132: If you want to generate a diff of a binary file that is safe to use as bos@132: input for \hgcmd{import}, use the \hgcmd{diff}{--git} option when you bos@132: generate the patch. The system \command{patch} command cannot handle bos@132: binary patches at all. bos@132: bos@132: %%% Local Variables: bos@132: %%% mode: latex bos@132: %%% TeX-master: "00book" bos@132: %%% End: