1.1 --- /dev/null	Thu Jan 01 00:00:00 1970 +0000
     1.2 +++ b/en/daily.tex	Sun Jul 23 09:46:26 2006 -0700
     1.3 @@ -0,0 +1,88 @@
     1.4 +\chapter{Mercurial in daily use}
     1.5 +\label{chap:daily}
     1.6 +
     1.7 +\section{Routine file management tasks}
     1.8 +
     1.9 +\subsection{Telling Mercurial which files to track}
    1.10 +
    1.11 +Mercurial does not work with files in your repository unless you tell
    1.12 +it to manage them.  The \hgcmd{status} command will tell you which
    1.13 +files Mercurial doesn't know about; it uses a ``\texttt{?}'' to
    1.14 +display such files.
    1.15 +
    1.16 +To tell Mercurial to track a file, use the \hgcmd{add} command.  Once
    1.17 +you have added a file, the entry in the output of \hgcmd{status} for
    1.18 +that file changes from ``\texttt{?}'' to ``\texttt{A}''.
    1.19 +
    1.20 +After you run a \hgcmd{commit}, the files that you added before the
    1.21 +commit will no longer be listed in the output of \hgcmd{status}.  The
    1.22 +reason for this is that \hgcmd{status} only tells you about
    1.23 +``interesting'' files by default.  If you have a repository that
    1.24 +contains thousands of files, you will rarely want to know about files
    1.25 +that Mercurial is tracking, but that have not changed.  (You can still
    1.26 +get this information; we'll return to this later.)
    1.27 +
    1.28 +\begin{figure}[ht]
    1.29 +  \interaction{daily.files.add}
    1.30 +  \caption{Telling Mercurial to track a file}
    1.31 +  \label{ex:daily:add}
    1.32 +\end{figure}
    1.33 +
    1.34 +Once you add a file, Mercurial will track every change you make to it
    1.35 +until you either remove or rename the file.
    1.36 +
    1.37 +\subsubsection{Aside: Mercurial tracks files, not directories}
    1.38 +
    1.39 +Mercurial does not track directory information.  Instead, it tracks
    1.40 +the path to a file, and creates directories along a path when it needs
    1.41 +to.  This sounds like a trivial distinction, but it has one minor
    1.42 +practical consequence: it is not possible to represent a completely
    1.43 +empty directory in Mercurial.
    1.44 +
    1.45 +Empty directories are rarely useful, and there are unintrusive
    1.46 +workarounds that you can use to achieve an appropriate effect.  The
    1.47 +developers of Mercurial thus felt that the complexity that would be
    1.48 +required to manage empty directories was not worth the limited benefit
    1.49 +this feature would bring.
    1.50 +
    1.51 +If you need an empty directory in your repository, there are a few
    1.52 +ways to achieve this. One is to create a directory, then \hgcmd{add} a
    1.53 +``hidden'' file to that directory.  On Unix-like systems, any file
    1.54 +name that begins with a period (``\texttt{.}'') is treated as hidden
    1.55 +by most commands and GUI tools.  This approach is illustrated in
    1.56 +figure~\ref{ex:daily:empty}.
    1.57 +
    1.58 +\begin{figure}[ht]
    1.59 +  \interaction{daily.files.empty}
    1.60 +  \caption{Simulating an empty directory}
    1.61 +  \label{ex:daily:empty}
    1.62 +\end{figure}
    1.63 +
    1.64 +Another way to tackle a need for an empty directory is to simply
    1.65 +create one in your automated build scripts before they will need it.
    1.66 +
    1.67 +\subsection{How to stop tracking a file}
    1.68 +
    1.69 +If you decide that a file no longer belongs in your repository, use
    1.70 +the \hgcmd{remove} command; this deletes the file, and tells Mercurial
    1.71 +to stop tracking it.
    1.72 +
    1.73 +You might wonder why Mercurial requires you to explicitly tell it that
    1.74 +you are deleting a file.  Earlier during the development of Mercurial,
    1.75 +you could simply delete a file however you pleased; Mercurial would
    1.76 +notice automatically when you next ran a \hgcmd{commit}, and stop
    1.77 +tracking the file.  In practice, this made it too easy to accidentally
    1.78 +stop Mercurial from tracking a file.
    1.79 +
    1.80 +If you forget to run \hgcmd{remove} to delete a file, you can run
    1.81 +\hgcmdopts{remove}{--after} later on, to tell Mercurial that you
    1.82 +deleted the file.
    1.83 +
    1.84 +\subsection{Useful shorthand---adding and removing files in one step}
    1.85 +
    1.86 +
    1.87 +
    1.88 +%%% Local Variables: 
    1.89 +%%% mode: latex
    1.90 +%%% TeX-master: "00book"
    1.91 +%%% End: