| rev |
line source |
|
bos@42
|
1 \chapter{Mercurial in daily use}
|
|
bos@42
|
2 \label{chap:daily}
|
|
bos@42
|
3
|
|
bos@42
|
4 \section{Routine file management tasks}
|
|
bos@42
|
5
|
|
bos@42
|
6 \subsection{Telling Mercurial which files to track}
|
|
bos@42
|
7
|
|
bos@42
|
8 Mercurial does not work with files in your repository unless you tell
|
|
bos@42
|
9 it to manage them. The \hgcmd{status} command will tell you which
|
|
bos@42
|
10 files Mercurial doesn't know about; it uses a ``\texttt{?}'' to
|
|
bos@42
|
11 display such files.
|
|
bos@42
|
12
|
|
bos@42
|
13 To tell Mercurial to track a file, use the \hgcmd{add} command. Once
|
|
bos@42
|
14 you have added a file, the entry in the output of \hgcmd{status} for
|
|
bos@42
|
15 that file changes from ``\texttt{?}'' to ``\texttt{A}''.
|
|
bos@42
|
16
|
|
bos@42
|
17 After you run a \hgcmd{commit}, the files that you added before the
|
|
bos@42
|
18 commit will no longer be listed in the output of \hgcmd{status}. The
|
|
bos@42
|
19 reason for this is that \hgcmd{status} only tells you about
|
|
bos@42
|
20 ``interesting'' files 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@42
|
25 \begin{figure}[ht]
|
|
bos@42
|
26 \interaction{daily.files.add}
|
|
bos@42
|
27 \caption{Telling Mercurial to track a file}
|
|
bos@42
|
28 \label{ex:daily:add}
|
|
bos@42
|
29 \end{figure}
|
|
bos@42
|
30
|
|
bos@42
|
31 Once you add a file, Mercurial will track every change you make to it
|
|
bos@42
|
32 until you either remove or rename the file.
|
|
bos@42
|
33
|
|
bos@42
|
34 \subsubsection{Aside: Mercurial tracks files, not directories}
|
|
bos@42
|
35
|
|
bos@42
|
36 Mercurial does not track directory information. Instead, it tracks
|
|
bos@42
|
37 the path to a file, and creates directories along a path when it needs
|
|
bos@42
|
38 to. This sounds like a trivial distinction, but it has one minor
|
|
bos@42
|
39 practical consequence: it is not possible to represent a completely
|
|
bos@42
|
40 empty directory in Mercurial.
|
|
bos@42
|
41
|
|
bos@42
|
42 Empty directories are rarely useful, and there are unintrusive
|
|
bos@42
|
43 workarounds that you can use to achieve an appropriate effect. The
|
|
bos@42
|
44 developers of Mercurial thus felt that the complexity that would be
|
|
bos@42
|
45 required to manage empty directories was not worth the limited benefit
|
|
bos@42
|
46 this feature would bring.
|
|
bos@42
|
47
|
|
bos@42
|
48 If you need an empty directory in your repository, there are a few
|
|
bos@42
|
49 ways to achieve this. One is to create a directory, then \hgcmd{add} a
|
|
bos@42
|
50 ``hidden'' file to that directory. On Unix-like systems, any file
|
|
bos@42
|
51 name that begins with a period (``\texttt{.}'') is treated as hidden
|
|
bos@42
|
52 by most commands and GUI tools. This approach is illustrated in
|
|
bos@42
|
53 figure~\ref{ex:daily:empty}.
|
|
bos@42
|
54
|
|
bos@42
|
55 \begin{figure}[ht]
|
|
bos@42
|
56 \interaction{daily.files.empty}
|
|
bos@42
|
57 \caption{Simulating an empty directory}
|
|
bos@42
|
58 \label{ex:daily:empty}
|
|
bos@42
|
59 \end{figure}
|
|
bos@42
|
60
|
|
bos@42
|
61 Another way to tackle a need for an empty directory is to simply
|
|
bos@42
|
62 create one in your automated build scripts before they will need it.
|
|
bos@42
|
63
|
|
bos@42
|
64 \subsection{How to stop tracking a file}
|
|
bos@42
|
65
|
|
bos@42
|
66 If you decide that a file no longer belongs in your repository, use
|
|
bos@42
|
67 the \hgcmd{remove} command; this deletes the file, and tells Mercurial
|
|
bos@42
|
68 to stop tracking it.
|
|
bos@42
|
69
|
|
bos@42
|
70 You might wonder why Mercurial requires you to explicitly tell it that
|
|
bos@42
|
71 you are deleting a file. Earlier during the development of Mercurial,
|
|
bos@42
|
72 you could simply delete a file however you pleased; Mercurial would
|
|
bos@42
|
73 notice automatically when you next ran a \hgcmd{commit}, and stop
|
|
bos@42
|
74 tracking the file. In practice, this made it too easy to accidentally
|
|
bos@42
|
75 stop Mercurial from tracking a file.
|
|
bos@42
|
76
|
|
bos@42
|
77 If you forget to run \hgcmd{remove} to delete a file, you can run
|
|
bos@42
|
78 \hgcmdopts{remove}{--after} later on, to tell Mercurial that you
|
|
bos@42
|
79 deleted the file.
|
|
bos@42
|
80
|
|
bos@42
|
81 \subsection{Useful shorthand---adding and removing files in one step}
|
|
bos@42
|
82
|
|
bos@42
|
83
|
|
bos@42
|
84
|
|
bos@42
|
85 %%% Local Variables:
|
|
bos@42
|
86 %%% mode: latex
|
|
bos@42
|
87 %%% TeX-master: "00book"
|
|
bos@42
|
88 %%% End:
|
