rev |
line source |
bos@42
|
1 \chapter{Mercurial in daily use}
|
bos@42
|
2 \label{chap:daily}
|
bos@42
|
3
|
bos@117
|
4 \section{Telling Mercurial which files to track}
|
bos@42
|
5
|
bos@42
|
6 Mercurial does not work with files in your repository unless you tell
|
bos@42
|
7 it to manage them. The \hgcmd{status} command will tell you which
|
bos@42
|
8 files Mercurial doesn't know about; it uses a ``\texttt{?}'' to
|
bos@42
|
9 display such files.
|
bos@42
|
10
|
bos@42
|
11 To tell Mercurial to track a file, use the \hgcmd{add} command. Once
|
bos@42
|
12 you have added a file, the entry in the output of \hgcmd{status} for
|
bos@42
|
13 that file changes from ``\texttt{?}'' to ``\texttt{A}''.
|
bos@117
|
14 \interaction{daily.files.add}
|
bos@42
|
15
|
bos@42
|
16 After you run a \hgcmd{commit}, the files that you added before the
|
bos@42
|
17 commit will no longer be listed in the output of \hgcmd{status}. The
|
bos@42
|
18 reason for this is that \hgcmd{status} only tells you about
|
bos@117
|
19 ``interesting'' files---those that you have modified or told Mercurial
|
bos@117
|
20 to do something with---by default. If you have a repository that
|
bos@42
|
21 contains thousands of files, you will rarely want to know about files
|
bos@42
|
22 that Mercurial is tracking, but that have not changed. (You can still
|
bos@42
|
23 get this information; we'll return to this later.)
|
bos@42
|
24
|
bos@117
|
25 Once you add a file, Mercurial doesn't do anything with it
|
bos@117
|
26 immediately. Instead, it will take a snapshot of the file's state the
|
bos@117
|
27 next time you perform a commit. It will then continue to track the
|
bos@117
|
28 changes you make to the file every time you commit, until you remove
|
bos@117
|
29 the file.
|
bos@117
|
30
|
bos@117
|
31 \subsection{Explicit versus implicit file naming}
|
bos@117
|
32
|
bos@117
|
33 A useful behaviour that Mercurial has is that if you pass the name of
|
bos@117
|
34 a directory to a command, every Mercurial command will treat this as
|
bos@117
|
35 ``I want to operate on every file in this directory and its
|
bos@117
|
36 subdirectories''.
|
bos@117
|
37 \interaction{daily.files.add-dir}
|
bos@117
|
38 Notice in this example that Mercurial printed the names of the files
|
bos@117
|
39 it added, whereas it didn't do so when we added the file named
|
bos@117
|
40 \filename{a} in the earlier example.
|
bos@117
|
41
|
bos@117
|
42 What's going on is that in the former case, we explicitly named the
|
bos@117
|
43 file to add on the command line, so the assumption that Mercurial
|
bos@117
|
44 makes in such cases is that we know what you were doing, and it
|
bos@117
|
45 doesn't print any output.
|
bos@117
|
46
|
bos@117
|
47 However, when we \emph{imply} the names of files by giving the name of
|
bos@117
|
48 a directory, Mercurial takes the extra step of printing the name of
|
bos@117
|
49 each file that it does something with. This makes it more clear what
|
bos@117
|
50 is happening, and reduces the likelihood of a silent and nasty
|
bos@117
|
51 surprise. This behaviour is common to most Mercurial commands.
|
bos@117
|
52
|
bos@117
|
53 \subsection{Aside: Mercurial tracks files, not directories}
|
bos@42
|
54
|
bos@42
|
55 Mercurial does not track directory information. Instead, it tracks
|
bos@117
|
56 the path to a file. Before creating a file, it first creates any
|
bos@117
|
57 missing directory components of the path. After it deletes a file, it
|
bos@117
|
58 then deletes any empty directories that were in the deleted file's
|
bos@117
|
59 path. This sounds like a trivial distinction, but it has one minor
|
bos@42
|
60 practical consequence: it is not possible to represent a completely
|
bos@42
|
61 empty directory in Mercurial.
|
bos@42
|
62
|
bos@42
|
63 Empty directories are rarely useful, and there are unintrusive
|
bos@42
|
64 workarounds that you can use to achieve an appropriate effect. The
|
bos@42
|
65 developers of Mercurial thus felt that the complexity that would be
|
bos@42
|
66 required to manage empty directories was not worth the limited benefit
|
bos@42
|
67 this feature would bring.
|
bos@42
|
68
|
bos@42
|
69 If you need an empty directory in your repository, there are a few
|
bos@42
|
70 ways to achieve this. One is to create a directory, then \hgcmd{add} a
|
bos@42
|
71 ``hidden'' file to that directory. On Unix-like systems, any file
|
bos@42
|
72 name that begins with a period (``\texttt{.}'') is treated as hidden
|
bos@42
|
73 by most commands and GUI tools. This approach is illustrated in
|
bos@43
|
74 figure~\ref{ex:daily:hidden}.
|
bos@42
|
75
|
bos@42
|
76 \begin{figure}[ht]
|
bos@43
|
77 \interaction{daily.files.hidden}
|
bos@43
|
78 \caption{Simulating an empty directory using a hidden file}
|
bos@43
|
79 \label{ex:daily:hidden}
|
bos@42
|
80 \end{figure}
|
bos@42
|
81
|
bos@42
|
82 Another way to tackle a need for an empty directory is to simply
|
bos@42
|
83 create one in your automated build scripts before they will need it.
|
bos@42
|
84
|
bos@117
|
85 \section{How to stop tracking a file}
|
bos@117
|
86
|
bos@117
|
87 Once you decide that a file no longer belongs in your repository, use
|
bos@42
|
88 the \hgcmd{remove} command; this deletes the file, and tells Mercurial
|
bos@43
|
89 to stop tracking it. A removed file is represented in the output of
|
bos@43
|
90 \hgcmd{status} with a ``\texttt{R}''.
|
bos@117
|
91 \interaction{daily.files.remove}
|
bos@117
|
92
|
bos@117
|
93 \subsection{Missing files}
|
bos@42
|
94
|
bos@43
|
95 Mercurial considers a file that you have deleted, but not used
|
bos@43
|
96 \hgcmd{remove} to delete, to be \emph{missing}. A missing file is
|
bos@43
|
97 represented with ``\texttt{!}'' in the output of \hgcmd{status}.
|
bos@117
|
98 Mercurial commands will not generally do anything with missing files.
|
bos@117
|
99 \interaction{daily.files.missing}
|
bos@117
|
100
|
bos@117
|
101 If your repository contains a file that \hgcmd{status} reports as
|
bos@117
|
102 missing, and you want the file to stay gone, you can run
|
bos@117
|
103 \hgcmdargs{remove}{\hgopt{remove}{--after}} at any time later on, to
|
bos@117
|
104 tell Mercurial that you really did mean to remove the file.
|
bos@117
|
105 \interaction{daily.files.remove-after}
|
bos@117
|
106
|
bos@117
|
107 On the other hand, if you deleted the missing file by accident, use
|
bos@117
|
108 \hgcmdargs{revert}{\emph{filename}} to recover the file. It will
|
bos@117
|
109 reappear, in unmodified form.
|
bos@117
|
110 \interaction{daily.files.recover-missing}
|
bos@117
|
111
|
bos@117
|
112 \subsection{Aside: why tell Mercurial explicitly to
|
bos@117
|
113 remove a file?}
|
bos@117
|
114
|
bos@117
|
115 You might wonder why Mercurial requires you to explicitly tell it that
|
bos@117
|
116 you are deleting a file. Early during the development of Mercurial,
|
bos@117
|
117 it let you delete a file however you pleased; Mercurial would notice
|
bos@117
|
118 the absence of the file automatically when you next ran a
|
bos@117
|
119 \hgcmd{commit}, and stop tracking the file. In practice, this made it
|
bos@117
|
120 too easy to accidentally remove a file without noticing.
|
bos@117
|
121
|
bos@117
|
122 \subsection{Useful shorthand---adding and removing files
|
bos@117
|
123 in one step}
|
bos@42
|
124
|
bos@43
|
125 Mercurial offers a combination command, \hgcmd{addremove}, that adds
|
bos@117
|
126 untracked files and marks missing files as removed.
|
bos@117
|
127 \interaction{daily.files.addremove}
|
bos@117
|
128 The \hgcmd{commit} command also provides a \hgopt{commit}{-A} option
|
bos@117
|
129 that performs this same add-and-remove, immediately followed by a
|
bos@117
|
130 commit.
|
bos@117
|
131 \interaction{daily.files.commit-addremove}
|
bos@117
|
132
|
bos@117
|
133 \section{Copying files}
|
bos@117
|
134
|
bos@117
|
135 Mercurial provides a \hgcmd{copy} command that lets you make a new
|
bos@117
|
136 copy of a file. When you copy a file using this command, Mercurial
|
bos@117
|
137 makes a record of the fact that the new file is a copy of the original
|
bos@117
|
138 file. It treats these copied files specially when you merge your work
|
bos@117
|
139 with someone else's.
|
bos@117
|
140
|
bos@117
|
141 What happens during a merge is that changes ``follow'' a copy. To
|
bos@117
|
142 best illustrate what this means, let's create an example. We'll start
|
bos@117
|
143 with the usual tiny repository that contains a single file.
|
bos@117
|
144 \interaction{daily.copy.init}
|
bos@117
|
145 We need to do some work in parallel, so that we'll have something to
|
bos@117
|
146 merge. So let's clone our repository.
|
bos@117
|
147 \interaction{daily.copy.clone}
|
bos@117
|
148 Back in our initial repository, let's use the \hgcmd{copy} command to
|
bos@117
|
149 make a copy of the first file we created.
|
bos@117
|
150 \interaction{daily.copy.copy}
|
bos@117
|
151
|
bos@117
|
152 If we look at the output of the \hgcmd{status} command afterwards, the
|
bos@117
|
153 copied file looks just like a normal added file.
|
bos@117
|
154 \interaction{daily.copy.status}
|
bos@117
|
155 But if we pass the \hgopt{status}{-C} option to \hgcmd{status}, it
|
bos@117
|
156 prints another line of output: this is the file that our newly-added
|
bos@117
|
157 file was copied \emph{from}.
|
bos@117
|
158 \interaction{daily.copy.status-copy}
|
bos@117
|
159
|
bos@117
|
160 Now, back in the repository we cloned, let's make a change in
|
bos@117
|
161 parallel. We'll add a line of content to the original file that we
|
bos@117
|
162 created.
|
bos@117
|
163 \interaction{daily.copy.other}
|
bos@117
|
164 Now we have a modified \filename{file} in this repository. When we
|
bos@117
|
165 pull the changes from the first repository, and merge the two heads,
|
bos@117
|
166 Mercurial will propagate the changes that we made locally to
|
bos@117
|
167 \filename{file} into its copy, \filename{new-file}.
|
bos@117
|
168 \interaction{daily.copy.merge}
|
bos@117
|
169
|
bos@117
|
170 \subsection{Why should changes follow copies?}
|
bos@117
|
171 \label{sec:daily:why-copy}
|
bos@117
|
172
|
bos@117
|
173 This behaviour, of changes to a file propagating out to copies of the
|
bos@117
|
174 file, might seem esoteric, but in most cases it's highly desirable.
|
bos@117
|
175
|
bos@117
|
176 First of all, remember that this propagation \emph{only} happens when
|
bos@117
|
177 you merge. So if you \hgcmd{copy} a file, and subsequently modify the
|
bos@117
|
178 original file during the normal course of your work, nothing will
|
bos@117
|
179 happen.
|
bos@117
|
180
|
bos@117
|
181 The second thing to know is that modifications will only propagate
|
bos@117
|
182 across a copy as long as the repository that you're pulling changes
|
bos@117
|
183 from \emph{doesn't know} about the copy.
|
bos@117
|
184
|
bos@117
|
185 The reason that Mercurial does this is as follows. Let's say I make
|
bos@117
|
186 an important bug fix in a source file, and commit my changes.
|
bos@117
|
187 Meanwhile, you've decided to \hgcmd{copy} the file in your repository,
|
bos@117
|
188 without knowing about the bug or having seen the fix, and you have
|
bos@117
|
189 started hacking on your copy of the file.
|
bos@117
|
190
|
bos@117
|
191 If you pulled and merged my changes, and Mercurial \emph{didn't}
|
bos@117
|
192 propagate changes across copies, your source file would now contain
|
bos@117
|
193 the bug, and unless you remembered to propagate the bug fix by hand,
|
bos@117
|
194 the bug would \emph{remain} in your copy of the file.
|
bos@117
|
195
|
bos@117
|
196 By automatically propagating the change that fixed the bug from the
|
bos@117
|
197 original file to the copy, Mercurial prevents this class of problem.
|
bos@117
|
198 To my knowledge, Mercurial is the \emph{only} revision control system
|
bos@117
|
199 that propagates changes across copies like this.
|
bos@117
|
200
|
bos@117
|
201 Once your change history has a record that the copy and subsequent
|
bos@117
|
202 merge occurred, there's usually no further need to propagate changes
|
bos@117
|
203 from the original file to the copied file, and that's why Mercurial
|
bos@117
|
204 only propagates changes across copies until this point, and no
|
bos@117
|
205 further.
|
bos@117
|
206
|
bos@117
|
207 \subsection{How to make changes \emph{not} follow a copy}
|
bos@117
|
208
|
bos@117
|
209 If, for some reason, you decide that this business of automatically
|
bos@117
|
210 propagating changes across copies is not for you, simply use your
|
bos@117
|
211 system's normal file copy command (on Unix-like systems, that's
|
bos@117
|
212 \command{cp}) to make a copy of a file, then \hgcmd{add} the new copy
|
bos@117
|
213 by hand. Before you do so, though, please do reread
|
bos@117
|
214 section~\ref{sec:daily:why-copy}, and make an informed decision that
|
bos@117
|
215 this behaviour is not appropriate to your specific case.
|
bos@117
|
216
|
bos@117
|
217 \subsection{Behaviour of the \hgcmd{copy} command}
|
bos@117
|
218
|
bos@117
|
219 The \hgcmd{copy} command acts similarly to the Unix \command{cp}
|
bos@117
|
220 command. The last argument is the \emph{destination}, and all prior
|
bos@117
|
221 arguments are \emph{sources}.
|
bos@117
|
222 If you pass it a single file as the source, and the destination
|
bos@117
|
223 does not exist, it creates a new file with that name.
|
bos@117
|
224 \interaction{daily.copy.simple}
|
bos@117
|
225 If the destination is a directory, Mercurial copies its sources into
|
bos@117
|
226 that directory.
|
bos@117
|
227 \interaction{daily.copy.dir-dest}
|
bos@117
|
228 Copying a directory is recursive, and preserves the directory
|
bos@117
|
229 structure of the source.
|
bos@117
|
230 \interaction{daily.copy.dir-src}
|
bos@117
|
231 If the source and destination are both directories, the source tree is
|
bos@117
|
232 recreated in the destination directory.
|
bos@117
|
233 \interaction{daily.copy.dir-src-dest}
|
bos@117
|
234
|
bos@117
|
235 \section{Renaming files}
|
bos@43
|
236
|
bos@43
|
237 To rename a file that is tracked by Mercurial, use the \hgcmd{rename}
|
bos@43
|
238 command. This command behaves similarly to the Unix \command{mv}
|
bos@117
|
239 command (and in fact you can use the alias \hgcmd{mv} if you wish).
|
bos@117
|
240 If the last argument is a directory, \hgcmd{rename} moves all files
|
bos@117
|
241 identified by earlier arguments into that directory. Otherwise, it
|
bos@117
|
242 renames a single file or directory to the name given in the last
|
bos@117
|
243 argument.
|
bos@43
|
244
|
bos@43
|
245 As with \hgcmd{remove}, you can tell Mercurial about a rename after
|
bos@43
|
246 the fact using the \hgopt{remove}{--after} option.
|
bos@43
|
247
|
bos@42
|
248 %%% Local Variables:
|
bos@42
|
249 %%% mode: latex
|
bos@42
|
250 %%% TeX-master: "00book"
|
bos@42
|
251 %%% End:
|