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