hgbook
diff en/concepts.tex @ 108:e0b961975c5e
First bit of concepts chapter.
author | Bryan O'Sullivan <bos@serpentine.com> |
---|---|
date | Thu Nov 09 10:11:31 2006 -0800 (2006-11-09) |
parents | b8539d91c84d |
children | 1b67dc96f27a |
line diff
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 -