| 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@43
|
53 figure~\ref{ex:daily:hidden}.
|
|
bos@42
|
54
|
|
bos@42
|
55 \begin{figure}[ht]
|
|
bos@43
|
56 \interaction{daily.files.hidden}
|
|
bos@43
|
57 \caption{Simulating an empty directory using a hidden file}
|
|
bos@43
|
58 \label{ex:daily:hidden}
|
|
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@43
|
68 to stop tracking it. A removed file is represented in the output of
|
|
bos@43
|
69 \hgcmd{status} with a ``\texttt{R}''.
|
|
bos@42
|
70
|
|
bos@42
|
71 You might wonder why Mercurial requires you to explicitly tell it that
|
|
bos@42
|
72 you are deleting a file. Earlier during the development of Mercurial,
|
|
bos@42
|
73 you could simply delete a file however you pleased; Mercurial would
|
|
bos@42
|
74 notice automatically when you next ran a \hgcmd{commit}, and stop
|
|
bos@42
|
75 tracking the file. In practice, this made it too easy to accidentally
|
|
bos@42
|
76 stop Mercurial from tracking a file.
|
|
bos@42
|
77
|
|
bos@43
|
78 Mercurial considers a file that you have deleted, but not used
|
|
bos@43
|
79 \hgcmd{remove} to delete, to be \emph{missing}. A missing file is
|
|
bos@43
|
80 represented with ``\texttt{!}'' in the output of \hgcmd{status}.
|
|
bos@43
|
81 Other Mercurial commands will not do anything with missing files.
|
|
bos@43
|
82
|
|
bos@43
|
83 If you have a missing file in your repository, you can run
|
|
bos@43
|
84 \hgcmdargs{remove}{\hgopt{remove}{--after}} later on, to tell
|
|
bos@43
|
85 Mercurial that you deleted the file. If you deleted the file by
|
|
bos@43
|
86 accident, use \hgcmdargs{revert}{\emph{filename}} to restore the file
|
|
bos@43
|
87 to its last committed state.
|
|
bos@42
|
88
|
|
bos@42
|
89 \subsection{Useful shorthand---adding and removing files in one step}
|
|
bos@42
|
90
|
|
bos@43
|
91 Mercurial offers a combination command, \hgcmd{addremove}, that adds
|
|
bos@43
|
92 untracked files and marks missing files as removed. The
|
|
bos@43
|
93 \hgcmd{commit} command also provides a \hgopt{commit}{-A} option that
|
|
bos@43
|
94 performs an add-and-remove, immediately followed by a commit. This
|
|
bos@43
|
95 lets you replace the following command sequence:
|
|
bos@43
|
96 \begin{codesample2}
|
|
bos@43
|
97 hg add
|
|
bos@43
|
98 hg remove --after
|
|
bos@43
|
99 hg commit
|
|
bos@43
|
100 \end{codesample2}
|
|
bos@43
|
101 with a single command, \hgcmdargs{commit}{\hgopt{commit}{-A}}.
|
|
bos@42
|
102
|
|
bos@43
|
103 \subsection{Renaming files}
|
|
bos@43
|
104
|
|
bos@43
|
105 To rename a file that is tracked by Mercurial, use the \hgcmd{rename}
|
|
bos@43
|
106 command. This command behaves similarly to the Unix \command{mv}
|
|
bos@43
|
107 command. If the last argument is a directory, it moves all prior
|
|
bos@43
|
108 arguments into that directory. Otherwise, it renames a single file or
|
|
bos@43
|
109 directory to the name given in the last argument.
|
|
bos@43
|
110
|
|
bos@43
|
111 As with \hgcmd{remove}, you can tell Mercurial about a rename after
|
|
bos@43
|
112 the fact using the \hgopt{remove}{--after} option.
|
|
bos@43
|
113
|
|
bos@43
|
114 The na\"{i}ve way to ``rename'' a file is simply to rename the file
|
|
bos@43
|
115 yourself, \hgcmd{remove} the old name, and \hgcmd{add} the new name.
|
|
bos@43
|
116 However, if you do this, Mercurial will not know that there was any
|
|
bos@43
|
117 relationship between the files in question, and it will not be able to
|
|
bos@43
|
118 merge
|
|
bos@43
|
119
|
|
bos@43
|
120 \subsection{Copying files}
|
|
bos@43
|
121
|
|
bos@43
|
122 You can copy a file in two ways using mercurial. If you simply copy a
|
|
bos@43
|
123 file and then \hgcmd{add} the new file, Mercurial will not know that
|
|
bos@43
|
124 there was any relationship between the two files. However, if you
|
|
bos@42
|
125
|
|
bos@42
|
126 %%% Local Variables:
|
|
bos@42
|
127 %%% mode: latex
|
|
bos@42
|
128 %%% TeX-master: "00book"
|
|
bos@42
|
129 %%% End:
|
