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@43: figure~\ref{ex:daily:hidden}.
bos@42: 
bos@42: \begin{figure}[ht]
bos@43:   \interaction{daily.files.hidden}
bos@43:   \caption{Simulating an empty directory using a hidden file}
bos@43:   \label{ex:daily:hidden}
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@43: to stop tracking it.  A removed file is represented in the output of
bos@43: \hgcmd{status} with a ``\texttt{R}''.
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@43: Mercurial considers a file that you have deleted, but not used
bos@43: \hgcmd{remove} to delete, to be \emph{missing}.  A missing file is
bos@43: represented with ``\texttt{!}'' in the output of \hgcmd{status}.
bos@43: Other Mercurial commands will not do anything with missing files.
bos@43: 
bos@43: If you have a missing file in your repository, you can run
bos@43: \hgcmdargs{remove}{\hgopt{remove}{--after}} later on, to tell
bos@43: Mercurial that you deleted the file.  If you deleted the file by
bos@43: accident, use \hgcmdargs{revert}{\emph{filename}} to restore the file
bos@43: to its last committed state.
bos@42: 
bos@42: \subsection{Useful shorthand---adding and removing files in one step}
bos@42: 
bos@43: Mercurial offers a combination command, \hgcmd{addremove}, that adds
bos@43: untracked files and marks missing files as removed.  The
bos@43: \hgcmd{commit} command also provides a \hgopt{commit}{-A} option that
bos@43: performs an add-and-remove, immediately followed by a commit.  This
bos@43: lets you replace the following command sequence:
bos@43: \begin{codesample2}
bos@43:   hg add
bos@43:   hg remove --after
bos@43:   hg commit
bos@43: \end{codesample2}
bos@43: with a single command, \hgcmdargs{commit}{\hgopt{commit}{-A}}.
bos@42: 
bos@43: \subsection{Renaming files}
bos@43: 
bos@43: To rename a file that is tracked by Mercurial, use the \hgcmd{rename}
bos@43: command.  This command behaves similarly to the Unix \command{mv}
bos@43: command.  If the last argument is a directory, it moves all prior
bos@43: arguments into that directory.  Otherwise, it renames a single file or
bos@43: directory to the name given in the last argument.
bos@43: 
bos@43: As with \hgcmd{remove}, you can tell Mercurial about a rename after
bos@43: the fact using the \hgopt{remove}{--after} option.
bos@43: 
bos@43: The na\"{i}ve way to ``rename'' a file is simply to rename the file
bos@43: yourself, \hgcmd{remove} the old name, and \hgcmd{add} the new name.
bos@43: However, if you do this, Mercurial will not know that there was any
bos@43: relationship between the files in question, and it will not be able to
bos@43: merge
bos@43: 
bos@43: \subsection{Copying files}
bos@43: 
bos@43: You can copy a file in two ways using mercurial.  If you simply copy a
bos@43: file and then \hgcmd{add} the new file, Mercurial will not know that
bos@43: there was any relationship between the two files.  However, if you 
bos@42: 
bos@42: %%% Local Variables: 
bos@42: %%% mode: latex
bos@42: %%% TeX-master: "00book"
bos@42: %%% End: