hgbook
diff en/daily.tex @ 42:cbfa08bcf181
Start the "Mercurial in daily use" chapter.
author | Bryan O'Sullivan <bos@serpentine.com> |
---|---|
date | Sun Jul 23 09:46:26 2006 -0700 (2006-07-23) |
parents | |
children | 7ac85766db0f |
line diff
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: