hgbook
annotate en/cmdref.tex @ 281:a880d07f2d29
Fix repository paths of data/index files in filelog diagram.
Data/index files are stored in the repository at .hg/store/data, not .hg/data.
Modify the filelog diagram to reflect this.
Data/index files are stored in the repository at .hg/store/data, not .hg/data.
Modify the filelog diagram to reflect this.
| author | Arun Thomas <arun.thomas@gmail.com> |
|---|---|
| date | Mon Dec 17 23:16:59 2007 -0500 (2007-12-17) |
| parents | 1e013fbe35f7 |
| children |
| 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 |
| dongsheng@276 | 32 Include files and directories whose names match the given patterns. |
| bos@133 | 33 |
| bos@133 | 34 \optref{diff}{X}{exclude} |
| bos@133 | 35 |
| dongsheng@276 | 36 Exclude 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: |