1.1 --- a/en/concepts.tex	Mon Jul 24 23:57:52 2006 -0400
     1.2 +++ b/en/concepts.tex	Thu Nov 09 10:11:31 2006 -0800
     1.3 @@ -1,131 +1,38 @@
     1.4 -\chapter{Basic Concepts}
     1.5 +\chapter{Behind the scenes}
     1.6  \label{chap:concepts}
     1.7  
     1.8 -This chapter introduces some of the basic concepts behind distributed
     1.9 -version control systems such as Mercurial.
    1.10 +Unlike many revision control systems, the concepts upon which
    1.11 +Mercurial is built are simple enough that it's easy to understand how
    1.12 +the software really works.  Knowing this certainly isn't necessary,
    1.13 +but I find it useful to have a ``mental model'' of what's going on.
    1.14  
    1.15 -\section{Repository}
    1.16 -\label{sec:concepts:repo}
    1.17 -The repository is a directory where Mercurial stores the history for the
    1.18 -files under revision control.
    1.19 +\section{Tracking the history of a single file}
    1.20  
    1.21 -\subsection{Where?}
    1.22 -% where is this repository you speak of?
    1.23 -XXX
    1.24 +When Mercurial tracks modifications to a file, it stores the history
    1.25 +of that file in a metadata object called a \emph{filelog}.  Each entry
    1.26 +in the filelog contains enough information to reconstruct one revision
    1.27 +of the file that is being tracked.  Filelogs are stored as files in
    1.28 +the \sdirname{.hg/data} directory.  A filelog contains two kinds of
    1.29 +information: revision data, and an index to help Mercurial to find a
    1.30 +revision efficiently.  
    1.31  
    1.32 -\subsection{How?}
    1.33 -% How are the changes stored?
    1.34 -XXX
    1.35 -
    1.36 -\subsection{Structure}
    1.37 -\label{sec:concepts:structure}
    1.38 -% What's the structure of the repository?
    1.39 -A typical Mercurial repository is a directory which contains a checked out
    1.40 -working copy (see section~\ref{sec:concepts:workingcopy}) as well as
    1.41 -\sdirname{.hg} directory.  Figure~\ref{ex:concepts:dirlist} shows the
    1.42 -contents of a freshly created repository.  This repository does not contain
    1.43 -any revisions. Let's take a look at a repository that has history for
    1.44 -several files.
    1.45 -Figure~\ref{ex:concepts:dirlist2} shows the contents of a repository keeping
    1.46 -history on two files.  We see the checked out copies of the files
    1.47 -\filename{foo} and \filename{bar}, as well as the files containing their
    1.48 -histories \filename{foo.i} and \filename{bar.i}, respectively. Additionally,
    1.49 -we see the \filename{changelog.i} and \filename{00manifest.i} files. These
    1.50 -contain the repository-wide revision data, such as the commit message, and
    1.51 -the list of files in the repository during the commit.
    1.52 +For small files without much history, the revision data and index are
    1.53 +combined in a single file (with a ``\texttt{.i}'' suffix).  A file
    1.54 +that is large, or has a lot of history, has its filelog stored as
    1.55 +separate data (``\texttt{.d}'' suffix) and index (``\texttt{.i}''
    1.56 +suffix) files.  The correspondence between a file in the working
    1.57 +directory and the filelog that tracks its history in the repository is
    1.58 +illustrated in figure~\ref{fig:concepts:filelog}.
    1.59  
    1.60  \begin{figure}[ht]
    1.61 -  \interaction{concepts.dirlist}
    1.62 -  \caption{Contents of a freshly created repository}
    1.63 -  \label{ex:concepts:dirlist}
    1.64 +  \centering
    1.65 +  \grafix{filelog}
    1.66 +  \caption{Relationships between files in working directory and
    1.67 +    filelogs in repository}
    1.68 +  \label{fig:concepts:filelog}
    1.69  \end{figure}
    1.70  
    1.71 -\begin{figure}[ht]
    1.72 -  \interaction{concepts.dirlist2}
    1.73 -  \caption{Contents of a repository tracking two files}
    1.74 -  \label{ex:concepts:dirlist2}
    1.75 -\end{figure}
    1.76 -
    1.77 -\subsection{hgrc}
    1.78 -% .hg/hgrc
    1.79 -XXX
    1.80 -
    1.81 -\subsection{Creating a Repository}
    1.82 -% hg init
    1.83 -Creating a repository is quick and painless.  One uses the \hgcmd{init}
    1.84 -command as figure~\ref{ex:concepts:hginit} demonstrates.  The one argument
    1.85 -passed to the \hgcmd{init} command is the name of the repository. The name
    1.86 -can be any string usable as a directory name.
    1.87 -
    1.88 -\begin{caution}
    1.89 -If you do not specify a name of the repository, the current working
    1.90 -directory will be used instead.
    1.91 -\end{caution}
    1.92 -
    1.93 -\begin{figure}[ht]
    1.94 -  \interaction{concepts.hginit}
    1.95 -  \caption{Creating a new repository}
    1.96 -  \label{ex:concepts:hginit}
    1.97 -\end{figure}
    1.98 -
    1.99 -\subsection{Remote Repositories}
   1.100 -\label{sec:concepts:remoterepo}
   1.101 -In addition to repositories stored on the local file system, Mercurial
   1.102 -supports so called \emph{remote repositories}.  These remote repositories
   1.103 -can be accessed via several different methods.  See
   1.104 -section~\ref{sec:XXX:remotesetup} for instructions how to set up remote
   1.105 -repositories.
   1.106 -% XXX: reference the proper section!
   1.107 -
   1.108 -\subsubsection{SSH}
   1.109 -\label{sec:concepts:remoterepo:ssh}
   1.110 -Mercurial can use \command{ssh} to send and receive changes. The remote
   1.111 -repository is identified by an URL. The basic format for the URL is:
   1.112 -
   1.113 -\begin{verbatim}
   1.114 -ssh://[user@]host/path
   1.115 -\end{verbatim}
   1.116 -
   1.117 -Where \cmdargs{user} is optional, and the \cmdargs{path} is path to the
   1.118 -repository --- either an absolute or relative to the user's home directory
   1.119 ---- on the remote host with hostname: \cmdargs{host}.
   1.120 -
   1.121 -\begin{note}
   1.122 -If the path for the remote repository is absolute there will be two
   1.123 -consecutive slashes.  E.g., if the remote path is \dirname{/repos/hgbook},
   1.124 -the URL would look something like the following:
   1.125 -
   1.126 -\begin{verbatim}
   1.127 -ssh://someuser@remotebox//repos/hgbook
   1.128 -\end{verbatim}
   1.129 -
   1.130 -Relative paths have only one slash and are relative to the user's home
   1.131 -directory.
   1.132 -\end{note}
   1.133 -
   1.134 -\subsubsection{HTTP \& HTTPS}
   1.135 -\label{sec:concepts:remoterepo:http}
   1.136 -The other protocol supported is HTTP as well as HTTPS.  The repository URL
   1.137 -is very much like that of the \command{ssh}.
   1.138 -
   1.139 -\begin{verbatim}
   1.140 -http://[user@]remotebox/path
   1.141 -\end{verbatim}
   1.142 -
   1.143 -Just as before, the username is optional.
   1.144 -% XXX: is it optional for both push & pull or just for pull?
   1.145 -This time however, the path is relative to the HTTP server root.  
   1.146 -
   1.147 -\section{Working Copy}
   1.148 -\label{sec:concepts:workingcopy}
   1.149 -XXX
   1.150 -
   1.151 -\section{Revisions}
   1.152 -\label{sec:concepts:revs}
   1.153 -XXX
   1.154 -
   1.155  %%% Local Variables: 
   1.156  %%% mode: latex
   1.157  %%% TeX-master: "00book"
   1.158  %%% End:
   1.159 -