# HG changeset patch # User Bryan O'Sullivan # Date 1163095891 28800 # Node ID e0b961975c5eccb94c38033566a151e45f301b78 # Parent a0d7e11db169e77982e6a2efe62a443462587c32 First bit of concepts chapter. diff -r a0d7e11db169 -r e0b961975c5e en/00book.tex --- a/en/00book.tex Tue Oct 24 11:25:56 2006 -0700 +++ b/en/00book.tex Thu Nov 09 10:11:31 2006 -0800 @@ -37,9 +37,9 @@ \include{preface} \include{intro} -%\include{concepts} \include{tour-basic} \include{tour-merge} +\include{concepts} \include{daily} \include{hook} \include{template} diff -r a0d7e11db169 -r e0b961975c5e en/Makefile --- a/en/Makefile Tue Oct 24 11:25:56 2006 -0700 +++ b/en/Makefile Thu Nov 09 10:11:31 2006 -0800 @@ -21,6 +21,7 @@ tour-merge.tex image-sources := \ + filelog.svg \ kdiff3.png \ mq-stack.svg \ tour-history.svg \ diff -r a0d7e11db169 -r e0b961975c5e en/concepts.tex --- a/en/concepts.tex Tue Oct 24 11:25:56 2006 -0700 +++ b/en/concepts.tex Thu Nov 09 10:11:31 2006 -0800 @@ -1,131 +1,38 @@ -\chapter{Basic Concepts} +\chapter{Behind the scenes} \label{chap:concepts} -This chapter introduces some of the basic concepts behind distributed -version control systems such as Mercurial. +Unlike many revision control systems, the concepts upon which +Mercurial is built are simple enough that it's easy to understand how +the software really works. Knowing this certainly isn't necessary, +but I find it useful to have a ``mental model'' of what's going on. -\section{Repository} -\label{sec:concepts:repo} -The repository is a directory where Mercurial stores the history for the -files under revision control. +\section{Tracking the history of a single file} -\subsection{Where?} -% where is this repository you speak of? -XXX +When Mercurial tracks modifications to a file, it stores the history +of that file in a metadata object called a \emph{filelog}. Each entry +in the filelog contains enough information to reconstruct one revision +of the file that is being tracked. Filelogs are stored as files in +the \sdirname{.hg/data} directory. A filelog contains two kinds of +information: revision data, and an index to help Mercurial to find a +revision efficiently. -\subsection{How?} -% How are the changes stored? -XXX - -\subsection{Structure} -\label{sec:concepts:structure} -% What's the structure of the repository? -A typical Mercurial repository is a directory which contains a checked out -working copy (see section~\ref{sec:concepts:workingcopy}) as well as -\sdirname{.hg} directory. Figure~\ref{ex:concepts:dirlist} shows the -contents of a freshly created repository. This repository does not contain -any revisions. Let's take a look at a repository that has history for -several files. -Figure~\ref{ex:concepts:dirlist2} shows the contents of a repository keeping -history on two files. We see the checked out copies of the files -\filename{foo} and \filename{bar}, as well as the files containing their -histories \filename{foo.i} and \filename{bar.i}, respectively. Additionally, -we see the \filename{changelog.i} and \filename{00manifest.i} files. These -contain the repository-wide revision data, such as the commit message, and -the list of files in the repository during the commit. +For small files without much history, the revision data and index are +combined in a single file (with a ``\texttt{.i}'' suffix). A file +that is large, or has a lot of history, has its filelog stored as +separate data (``\texttt{.d}'' suffix) and index (``\texttt{.i}'' +suffix) files. The correspondence between a file in the working +directory and the filelog that tracks its history in the repository is +illustrated in figure~\ref{fig:concepts:filelog}. \begin{figure}[ht] - \interaction{concepts.dirlist} - \caption{Contents of a freshly created repository} - \label{ex:concepts:dirlist} + \centering + \grafix{filelog} + \caption{Relationships between files in working directory and + filelogs in repository} + \label{fig:concepts:filelog} \end{figure} -\begin{figure}[ht] - \interaction{concepts.dirlist2} - \caption{Contents of a repository tracking two files} - \label{ex:concepts:dirlist2} -\end{figure} - -\subsection{hgrc} -% .hg/hgrc -XXX - -\subsection{Creating a Repository} -% hg init -Creating a repository is quick and painless. One uses the \hgcmd{init} -command as figure~\ref{ex:concepts:hginit} demonstrates. The one argument -passed to the \hgcmd{init} command is the name of the repository. The name -can be any string usable as a directory name. - -\begin{caution} -If you do not specify a name of the repository, the current working -directory will be used instead. -\end{caution} - -\begin{figure}[ht] - \interaction{concepts.hginit} - \caption{Creating a new repository} - \label{ex:concepts:hginit} -\end{figure} - -\subsection{Remote Repositories} -\label{sec:concepts:remoterepo} -In addition to repositories stored on the local file system, Mercurial -supports so called \emph{remote repositories}. These remote repositories -can be accessed via several different methods. See -section~\ref{sec:XXX:remotesetup} for instructions how to set up remote -repositories. -% XXX: reference the proper section! - -\subsubsection{SSH} -\label{sec:concepts:remoterepo:ssh} -Mercurial can use \command{ssh} to send and receive changes. The remote -repository is identified by an URL. The basic format for the URL is: - -\begin{verbatim} -ssh://[user@]host/path -\end{verbatim} - -Where \cmdargs{user} is optional, and the \cmdargs{path} is path to the -repository --- either an absolute or relative to the user's home directory ---- on the remote host with hostname: \cmdargs{host}. - -\begin{note} -If the path for the remote repository is absolute there will be two -consecutive slashes. E.g., if the remote path is \dirname{/repos/hgbook}, -the URL would look something like the following: - -\begin{verbatim} -ssh://someuser@remotebox//repos/hgbook -\end{verbatim} - -Relative paths have only one slash and are relative to the user's home -directory. -\end{note} - -\subsubsection{HTTP \& HTTPS} -\label{sec:concepts:remoterepo:http} -The other protocol supported is HTTP as well as HTTPS. The repository URL -is very much like that of the \command{ssh}. - -\begin{verbatim} -http://[user@]remotebox/path -\end{verbatim} - -Just as before, the username is optional. -% XXX: is it optional for both push & pull or just for pull? -This time however, the path is relative to the HTTP server root. - -\section{Working Copy} -\label{sec:concepts:workingcopy} -XXX - -\section{Revisions} -\label{sec:concepts:revs} -XXX - %%% Local Variables: %%% mode: latex %%% TeX-master: "00book" %%% End: - diff -r a0d7e11db169 -r e0b961975c5e en/filelog.svg --- /dev/null Thu Jan 01 00:00:00 1970 +0000 +++ b/en/filelog.svg Thu Nov 09 10:11:31 2006 -0800 @@ -0,0 +1,371 @@ + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + image/svg+xml + + + + + + + + + + + .hg/data/README.i + + + + + README + + + + + + + + + .hg/data/src/hello.c.d + .hg/data/src/hello.c.i + + + + + src/hello.c + + + + Working directory + Repository + +