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