bos@42: \chapter{Mercurial in daily use}
bos@42: \label{chap:daily}
bos@42: 
bos@42: \section{Routine file management tasks}
bos@42: 
bos@42: \subsection{Telling Mercurial which files to track}
bos@42: 
bos@42: Mercurial does not work with files in your repository unless you tell
bos@42: it to manage them.  The \hgcmd{status} command will tell you which
bos@42: files Mercurial doesn't know about; it uses a ``\texttt{?}'' to
bos@42: display such files.
bos@42: 
bos@42: To tell Mercurial to track a file, use the \hgcmd{add} command.  Once
bos@42: you have added a file, the entry in the output of \hgcmd{status} for
bos@42: that file changes from ``\texttt{?}'' to ``\texttt{A}''.
bos@42: 
bos@42: After you run a \hgcmd{commit}, the files that you added before the
bos@42: commit will no longer be listed in the output of \hgcmd{status}.  The
bos@42: reason for this is that \hgcmd{status} only tells you about
bos@42: ``interesting'' files by default.  If you have a repository that
bos@42: contains thousands of files, you will rarely want to know about files
bos@42: that Mercurial is tracking, but that have not changed.  (You can still
bos@42: get this information; we'll return to this later.)
bos@42: 
bos@42: \begin{figure}[ht]
bos@42:   \interaction{daily.files.add}
bos@42:   \caption{Telling Mercurial to track a file}
bos@42:   \label{ex:daily:add}
bos@42: \end{figure}
bos@42: 
bos@42: Once you add a file, Mercurial will track every change you make to it
bos@42: until you either remove or rename the file.
bos@42: 
bos@42: \subsubsection{Aside: Mercurial tracks files, not directories}
bos@42: 
bos@42: Mercurial does not track directory information.  Instead, it tracks
bos@42: the path to a file, and creates directories along a path when it needs
bos@42: to.  This sounds like a trivial distinction, but it has one minor
bos@42: practical consequence: it is not possible to represent a completely
bos@42: empty directory in Mercurial.
bos@42: 
bos@42: Empty directories are rarely useful, and there are unintrusive
bos@42: workarounds that you can use to achieve an appropriate effect.  The
bos@42: developers of Mercurial thus felt that the complexity that would be
bos@42: required to manage empty directories was not worth the limited benefit
bos@42: this feature would bring.
bos@42: 
bos@42: If you need an empty directory in your repository, there are a few
bos@42: ways to achieve this. One is to create a directory, then \hgcmd{add} a
bos@42: ``hidden'' file to that directory.  On Unix-like systems, any file
bos@42: name that begins with a period (``\texttt{.}'') is treated as hidden
bos@42: by most commands and GUI tools.  This approach is illustrated in
bos@42: figure~\ref{ex:daily:empty}.
bos@42: 
bos@42: \begin{figure}[ht]
bos@42:   \interaction{daily.files.empty}
bos@42:   \caption{Simulating an empty directory}
bos@42:   \label{ex:daily:empty}
bos@42: \end{figure}
bos@42: 
bos@42: Another way to tackle a need for an empty directory is to simply
bos@42: create one in your automated build scripts before they will need it.
bos@42: 
bos@42: \subsection{How to stop tracking a file}
bos@42: 
bos@42: If you decide that a file no longer belongs in your repository, use
bos@42: the \hgcmd{remove} command; this deletes the file, and tells Mercurial
bos@42: to stop tracking it.
bos@42: 
bos@42: You might wonder why Mercurial requires you to explicitly tell it that
bos@42: you are deleting a file.  Earlier during the development of Mercurial,
bos@42: you could simply delete a file however you pleased; Mercurial would
bos@42: notice automatically when you next ran a \hgcmd{commit}, and stop
bos@42: tracking the file.  In practice, this made it too easy to accidentally
bos@42: stop Mercurial from tracking a file.
bos@42: 
bos@42: If you forget to run \hgcmd{remove} to delete a file, you can run
bos@42: \hgcmdopts{remove}{--after} later on, to tell Mercurial that you
bos@42: deleted the file.
bos@42: 
bos@42: \subsection{Useful shorthand---adding and removing files in one step}
bos@42: 
bos@42: 
bos@42: 
bos@42: %%% Local Variables: 
bos@42: %%% mode: latex
bos@42: %%% TeX-master: "00book"
bos@42: %%% End: