hgbook
changeset 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 | d1a3394f8bcf |
children | 7ac85766db0f |
files | en/00book.tex en/Makefile en/daily.tex en/examples/daily.files |
line diff
1.1 --- a/en/00book.tex Thu Jul 20 19:42:50 2006 -0700 1.2 +++ b/en/00book.tex Sun Jul 23 09:46:26 2006 -0700 1.3 @@ -37,6 +37,7 @@ 1.4 1.5 \include{preface} 1.6 \include{intro} 1.7 +\include{daily} 1.8 \include{hook} 1.9 \include{mq} 1.10
2.1 --- a/en/Makefile Thu Jul 20 19:42:50 2006 -0700 2.2 +++ b/en/Makefile Sun Jul 23 09:46:26 2006 -0700 2.3 @@ -7,6 +7,7 @@ 2.4 99book.bib \ 2.5 99defs.tex \ 2.6 build_id.tex \ 2.7 + daily.tex \ 2.8 hook.tex \ 2.9 intro.tex \ 2.10 mq.tex \
3.1 --- /dev/null Thu Jan 01 00:00:00 1970 +0000 3.2 +++ b/en/daily.tex Sun Jul 23 09:46:26 2006 -0700 3.3 @@ -0,0 +1,88 @@ 3.4 +\chapter{Mercurial in daily use} 3.5 +\label{chap:daily} 3.6 + 3.7 +\section{Routine file management tasks} 3.8 + 3.9 +\subsection{Telling Mercurial which files to track} 3.10 + 3.11 +Mercurial does not work with files in your repository unless you tell 3.12 +it to manage them. The \hgcmd{status} command will tell you which 3.13 +files Mercurial doesn't know about; it uses a ``\texttt{?}'' to 3.14 +display such files. 3.15 + 3.16 +To tell Mercurial to track a file, use the \hgcmd{add} command. Once 3.17 +you have added a file, the entry in the output of \hgcmd{status} for 3.18 +that file changes from ``\texttt{?}'' to ``\texttt{A}''. 3.19 + 3.20 +After you run a \hgcmd{commit}, the files that you added before the 3.21 +commit will no longer be listed in the output of \hgcmd{status}. The 3.22 +reason for this is that \hgcmd{status} only tells you about 3.23 +``interesting'' files by default. If you have a repository that 3.24 +contains thousands of files, you will rarely want to know about files 3.25 +that Mercurial is tracking, but that have not changed. (You can still 3.26 +get this information; we'll return to this later.) 3.27 + 3.28 +\begin{figure}[ht] 3.29 + \interaction{daily.files.add} 3.30 + \caption{Telling Mercurial to track a file} 3.31 + \label{ex:daily:add} 3.32 +\end{figure} 3.33 + 3.34 +Once you add a file, Mercurial will track every change you make to it 3.35 +until you either remove or rename the file. 3.36 + 3.37 +\subsubsection{Aside: Mercurial tracks files, not directories} 3.38 + 3.39 +Mercurial does not track directory information. Instead, it tracks 3.40 +the path to a file, and creates directories along a path when it needs 3.41 +to. This sounds like a trivial distinction, but it has one minor 3.42 +practical consequence: it is not possible to represent a completely 3.43 +empty directory in Mercurial. 3.44 + 3.45 +Empty directories are rarely useful, and there are unintrusive 3.46 +workarounds that you can use to achieve an appropriate effect. The 3.47 +developers of Mercurial thus felt that the complexity that would be 3.48 +required to manage empty directories was not worth the limited benefit 3.49 +this feature would bring. 3.50 + 3.51 +If you need an empty directory in your repository, there are a few 3.52 +ways to achieve this. One is to create a directory, then \hgcmd{add} a 3.53 +``hidden'' file to that directory. On Unix-like systems, any file 3.54 +name that begins with a period (``\texttt{.}'') is treated as hidden 3.55 +by most commands and GUI tools. This approach is illustrated in 3.56 +figure~\ref{ex:daily:empty}. 3.57 + 3.58 +\begin{figure}[ht] 3.59 + \interaction{daily.files.empty} 3.60 + \caption{Simulating an empty directory} 3.61 + \label{ex:daily:empty} 3.62 +\end{figure} 3.63 + 3.64 +Another way to tackle a need for an empty directory is to simply 3.65 +create one in your automated build scripts before they will need it. 3.66 + 3.67 +\subsection{How to stop tracking a file} 3.68 + 3.69 +If you decide that a file no longer belongs in your repository, use 3.70 +the \hgcmd{remove} command; this deletes the file, and tells Mercurial 3.71 +to stop tracking it. 3.72 + 3.73 +You might wonder why Mercurial requires you to explicitly tell it that 3.74 +you are deleting a file. Earlier during the development of Mercurial, 3.75 +you could simply delete a file however you pleased; Mercurial would 3.76 +notice automatically when you next ran a \hgcmd{commit}, and stop 3.77 +tracking the file. In practice, this made it too easy to accidentally 3.78 +stop Mercurial from tracking a file. 3.79 + 3.80 +If you forget to run \hgcmd{remove} to delete a file, you can run 3.81 +\hgcmdopts{remove}{--after} later on, to tell Mercurial that you 3.82 +deleted the file. 3.83 + 3.84 +\subsection{Useful shorthand---adding and removing files in one step} 3.85 + 3.86 + 3.87 + 3.88 +%%% Local Variables: 3.89 +%%% mode: latex 3.90 +%%% TeX-master: "00book" 3.91 +%%% End:
4.1 --- /dev/null Thu Jan 01 00:00:00 1970 +0000 4.2 +++ b/en/examples/daily.files Sun Jul 23 09:46:26 2006 -0700 4.3 @@ -0,0 +1,20 @@ 4.4 +#$ name: status 4.5 + 4.6 +hg init a 4.7 +cd a 4.8 +echo content > filename 4.9 +mkdir subdir 4.10 +echo something > subdir/otherfile 4.11 +hg status 4.12 + 4.13 +#$ name: hidden 4.14 + 4.15 +mkdir empty 4.16 +touch empty/.hidden 4.17 +hg add empty/.hidden 4.18 +hg commit -m 'Manage an empty-looking directory' 4.19 +ls empty 4.20 +cd .. 4.21 +hg clone a b 4.22 +ls b 4.23 +ls b/empty