Mercurial > hgbook

changeset 108:e0b961975c5e

Find changesets by keywords (author, files, the commit message), revision number or hash, or revset expression.
First bit of concepts chapter.
author Bryan O'Sullivan <bos@serpentine.com>
date Thu, 09 Nov 2006 10:11:31 -0800
parents a0d7e11db169
children 1b67dc96f27a
files en/00book.tex en/Makefile en/concepts.tex en/filelog.svg
diffstat 4 files changed, 398 insertions(+), 119 deletions(-) [+]
line wrap: on
line diff
--- 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}
--- 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 \
--- 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.
-
-\section{Repository}
-\label{sec:concepts:repo}
-The repository is a directory where Mercurial stores the history for the
-files under revision control.
+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.
 
-\subsection{Where?}
-% where is this repository you speak of?
-XXX
-
-\subsection{How?}
-% How are the changes stored?
-XXX
+\section{Tracking the history of a single file}
 
-\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.
+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.  
 
-\begin{figure}[ht]
-  \interaction{concepts.dirlist}
-  \caption{Contents of a freshly created repository}
-  \label{ex:concepts:dirlist}
-\end{figure}
+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.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}
+  \centering
+  \grafix{filelog}
+  \caption{Relationships between files in working directory and
+    filelogs in repository}
+  \label{fig:concepts:filelog}
 \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:
-
--- /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 @@
+<?xml version="1.0" encoding="UTF-8" standalone="no"?>
+<!-- Created with Inkscape (http://www.inkscape.org/) -->
+<svg
+   xmlns:dc="http://purl.org/dc/elements/1.1/"
+   xmlns:cc="http://web.resource.org/cc/"
+   xmlns:rdf="http://www.w3.org/1999/02/22-rdf-syntax-ns#"
+   xmlns:svg="http://www.w3.org/2000/svg"
+   xmlns="http://www.w3.org/2000/svg"
+   xmlns:xlink="http://www.w3.org/1999/xlink"
+   xmlns:sodipodi="http://sodipodi.sourceforge.net/DTD/sodipodi-0.dtd"
+   xmlns:inkscape="http://www.inkscape.org/namespaces/inkscape"
+   width="744.09448819"
+   height="1052.3622047"
+   id="svg2"
+   sodipodi:version="0.32"
+   inkscape:version="0.44.1"
+   sodipodi:docname="filelog.svg">
+  <defs
+     id="defs4">
+    <marker
+       inkscape:stockid="Arrow1Mend"
+       orient="auto"
+       refY="0.0"
+       refX="0.0"
+       id="Arrow1Mend"
+       style="overflow:visible;">
+      <path
+         id="path3128"
+         d="M 0.0,0.0 L 5.0,-5.0 L -12.5,0.0 L 5.0,5.0 L 0.0,0.0 z "
+         style="fill-rule:evenodd;stroke:#000000;stroke-width:1.0pt;marker-start:none;"
+         transform="scale(0.4) rotate(180) translate(10,0)" />
+    </marker>
+    <linearGradient
+       id="linearGradient2887">
+      <stop
+         style="stop-color:#91cfcf;stop-opacity:1;"
+         offset="0"
+         id="stop2889" />
+      <stop
+         style="stop-color:aqua;stop-opacity:0;"
+         offset="1"
+         id="stop2891" />
+    </linearGradient>
+    <linearGradient
+       id="linearGradient2795">
+      <stop
+         style="stop-color:#ccc;stop-opacity:1;"
+         offset="0"
+         id="stop2797" />
+      <stop
+         style="stop-color:#ccc;stop-opacity:0;"
+         offset="1"
+         id="stop2799" />
+    </linearGradient>
+    <linearGradient
+       inkscape:collect="always"
+       xlink:href="#linearGradient2795"
+       id="linearGradient3170"
+       gradientUnits="userSpaceOnUse"
+       gradientTransform="translate(121.2183,94.95434)"
+       x1="81.322357"
+       y1="404.34424"
+       x2="201.52036"
+       y2="373.03967" />
+    <linearGradient
+       inkscape:collect="always"
+       xlink:href="#linearGradient2887"
+       id="linearGradient3172"
+       gradientUnits="userSpaceOnUse"
+       gradientTransform="translate(0,12)"
+       x1="62.634491"
+       y1="503.3392"
+       x2="248.49242"
+       y2="462.94327" />
+    <linearGradient
+       inkscape:collect="always"
+       xlink:href="#linearGradient2795"
+       id="linearGradient3174"
+       gradientUnits="userSpaceOnUse"
+       gradientTransform="matrix(1.001035,0,0,0.653159,236.7075,153.0415)"
+       x1="81.322357"
+       y1="404.34424"
+       x2="201.52036"
+       y2="373.03967" />
+    <linearGradient
+       inkscape:collect="always"
+       xlink:href="#linearGradient2887"
+       id="linearGradient3176"
+       gradientUnits="userSpaceOnUse"
+       gradientTransform="translate(0,12)"
+       x1="62.634491"
+       y1="503.3392"
+       x2="248.49242"
+       y2="462.94327" />
+    <linearGradient
+       inkscape:collect="always"
+       xlink:href="#linearGradient2795"
+       id="linearGradient3208"
+       gradientUnits="userSpaceOnUse"
+       gradientTransform="matrix(1.001035,0,0,0.653159,236.7075,153.0415)"
+       x1="81.322357"
+       y1="404.34424"
+       x2="201.52036"
+       y2="373.03967" />
+    <linearGradient
+       inkscape:collect="always"
+       xlink:href="#linearGradient2887"
+       id="linearGradient3210"
+       gradientUnits="userSpaceOnUse"
+       gradientTransform="translate(0,12)"
+       x1="62.634491"
+       y1="503.3392"
+       x2="248.49242"
+       y2="462.94327" />
+    <linearGradient
+       inkscape:collect="always"
+       xlink:href="#linearGradient2795"
+       id="linearGradient3212"
+       gradientUnits="userSpaceOnUse"
+       gradientTransform="translate(121.2183,94.95434)"
+       x1="81.322357"
+       y1="404.34424"
+       x2="201.52036"
+       y2="373.03967" />
+    <linearGradient
+       inkscape:collect="always"
+       xlink:href="#linearGradient2887"
+       id="linearGradient3214"
+       gradientUnits="userSpaceOnUse"
+       gradientTransform="translate(0,12)"
+       x1="62.634491"
+       y1="503.3392"
+       x2="248.49242"
+       y2="462.94327" />
+    <linearGradient
+       inkscape:collect="always"
+       xlink:href="#linearGradient2795"
+       id="linearGradient3256"
+       gradientUnits="userSpaceOnUse"
+       gradientTransform="translate(121.2183,94.95434)"
+       x1="81.322357"
+       y1="404.34424"
+       x2="201.52036"
+       y2="373.03967" />
+    <linearGradient
+       inkscape:collect="always"
+       xlink:href="#linearGradient2887"
+       id="linearGradient3258"
+       gradientUnits="userSpaceOnUse"
+       gradientTransform="translate(0,12)"
+       x1="62.634491"
+       y1="503.3392"
+       x2="248.49242"
+       y2="462.94327" />
+    <linearGradient
+       inkscape:collect="always"
+       xlink:href="#linearGradient2795"
+       id="linearGradient3260"
+       gradientUnits="userSpaceOnUse"
+       gradientTransform="matrix(1.001035,0,0,0.653159,236.7075,153.0415)"
+       x1="81.322357"
+       y1="404.34424"
+       x2="201.52036"
+       y2="373.03967" />
+    <linearGradient
+       inkscape:collect="always"
+       xlink:href="#linearGradient2887"
+       id="linearGradient3262"
+       gradientUnits="userSpaceOnUse"
+       gradientTransform="translate(0,12)"
+       x1="62.634491"
+       y1="503.3392"
+       x2="248.49242"
+       y2="462.94327" />
+  </defs>
+  <sodipodi:namedview
+     id="base"
+     pagecolor="#ffffff"
+     bordercolor="#666666"
+     borderopacity="1.0"
+     gridtolerance="10000"
+     guidetolerance="10"
+     objecttolerance="10"
+     inkscape:pageopacity="0.0"
+     inkscape:pageshadow="2"
+     inkscape:zoom="0.98994949"
+     inkscape:cx="455.8122"
+     inkscape:cy="520"
+     inkscape:document-units="px"
+     inkscape:current-layer="layer1"
+     inkscape:window-width="906"
+     inkscape:window-height="620"
+     inkscape:window-x="5"
+     inkscape:window-y="49" />
+  <metadata
+     id="metadata7">
+    <rdf:RDF>
+      <cc:Work
+         rdf:about="">
+        <dc:format>image/svg+xml</dc:format>
+        <dc:type
+           rdf:resource="http://purl.org/dc/dcmitype/StillImage" />
+      </cc:Work>
+    </rdf:RDF>
+  </metadata>
+  <g
+     inkscape:label="Layer 1"
+     inkscape:groupmode="layer"
+     id="layer1">
+    <rect
+       style="opacity:1;fill:#abadf8;fill-opacity:1;stroke:#595959;stroke-width:0.86781615;stroke-linecap:round;stroke-linejoin:round;stroke-miterlimit:4;stroke-dasharray:none;stroke-dashoffset:0;stroke-opacity:1"
+       id="rect3180"
+       width="234.48758"
+       height="199.13225"
+       x="322.67767"
+       y="351.75531" />
+    <rect
+       style="opacity:1;fill:#a2f69c;fill-opacity:1;stroke:#595959;stroke-width:0.86781615;stroke-linecap:round;stroke-linejoin:round;stroke-miterlimit:4;stroke-dasharray:none;stroke-dashoffset:0;stroke-opacity:1"
+       id="rect3178"
+       width="234.48756"
+       height="199.13223"
+       x="72.664886"
+       y="351.75531" />
+    <g
+       id="g3144"
+       transform="translate(34,0.71578)">
+      <g
+         id="g2940">
+        <rect
+           style="fill:url(#linearGradient3260);fill-opacity:1;stroke:black;stroke-width:0.80860078;stroke-linecap:round;stroke-linejoin:round;stroke-miterlimit:4;stroke-dasharray:none;stroke-dashoffset:0;stroke-opacity:1"
+           id="rect2914"
+           width="185.04932"
+           height="39.587399"
+           x="311.53635"
+           y="395.04291" />
+        <text
+           xml:space="preserve"
+           style="font-size:12px;font-style:normal;font-weight:normal;fill:black;fill-opacity:1;stroke:none;stroke-width:1px;stroke-linecap:butt;stroke-linejoin:miter;stroke-opacity:1;font-family:Times New Roman"
+           x="323.72824"
+           y="416.7626"
+           id="text2918"><tspan
+             sodipodi:role="line"
+             id="tspan2920"
+             x="323.72824"
+             y="416.7626"
+             style="font-family:Courier">.hg/data/README.i</tspan></text>
+      </g>
+      <g
+         transform="translate(3.79093e-5,-80.1853)"
+         id="g2945">
+        <g
+           id="g2955">
+          <rect
+             y="475.44327"
+             x="63.134491"
+             height="39.395935"
+             width="184.85793"
+             id="rect2947"
+             style="fill:url(#linearGradient3262);fill-opacity:1;stroke:black;stroke-width:1;stroke-linecap:round;stroke-linejoin:round;stroke-miterlimit:4;stroke-dasharray:none;stroke-dashoffset:0;stroke-opacity:1" />
+          <text
+             id="text2949"
+             y="498.35123"
+             x="75.230644"
+             style="font-size:12px;font-style:normal;font-weight:normal;fill:black;fill-opacity:1;stroke:none;stroke-width:1px;stroke-linecap:butt;stroke-linejoin:miter;stroke-opacity:1;font-family:Times New Roman"
+             xml:space="preserve"><tspan
+               style="font-family:Courier"
+               y="498.35123"
+               x="75.230644"
+               id="tspan2951"
+               sodipodi:role="line">README</tspan></text>
+        </g>
+      </g>
+      <path
+         inkscape:connection-end="#g2940"
+         inkscape:connection-start="#g2945"
+         inkscape:connector-type="polyline"
+         id="path2960"
+         d="M 248.49245,414.91131 L 311.13205,414.88123"
+         style="fill:none;fill-opacity:0.75;fill-rule:evenodd;stroke:black;stroke-width:1px;stroke-linecap:butt;stroke-linejoin:miter;marker-end:url(#Arrow1Mend);stroke-opacity:1" />
+    </g>
+    <g
+       id="g3156"
+       transform="translate(34,0.71578)">
+      <g
+         transform="translate(116,0)"
+         id="g2831">
+        <rect
+           style="fill:url(#linearGradient3256);fill-opacity:1;stroke:black;stroke-width:1;stroke-linecap:round;stroke-linejoin:round;stroke-miterlimit:4;stroke-dasharray:none;stroke-dashoffset:0;stroke-opacity:1"
+           id="rect1906"
+           width="184.85793"
+           height="60.609138"
+           x="195.96959"
+           y="465.46356" />
+        <g
+           id="g2803"
+           transform="translate(-0.893671,1.833581)">
+          <text
+             id="text1884"
+             y="483.92801"
+             x="208.95944"
+             style="font-size:12px;font-style:normal;font-weight:normal;fill:black;fill-opacity:1;stroke:none;stroke-width:1px;stroke-linecap:butt;stroke-linejoin:miter;stroke-opacity:1;font-family:Times New Roman"
+             xml:space="preserve"><tspan
+               style="font-family:Courier"
+               y="483.92801"
+               x="208.95944"
+               id="tspan1886"
+               sodipodi:role="line">.hg/data/src/hello.c.d</tspan></text>
+          <text
+             id="text1888"
+             y="507.79309"
+             x="208.95944"
+             style="font-size:12px;font-style:normal;font-weight:normal;fill:black;fill-opacity:1;stroke:none;stroke-width:1px;stroke-linecap:butt;stroke-linejoin:miter;stroke-opacity:1;font-family:Times New Roman"
+             xml:space="preserve"><tspan
+               style="font-family:Courier"
+               y="507.79309"
+               x="208.95944"
+               id="tspan1890"
+               sodipodi:role="line">.hg/data/src/hello.c.i</tspan></text>
+        </g>
+      </g>
+      <g
+         id="g2907">
+        <rect
+           style="fill:url(#linearGradient3258);fill-opacity:1;stroke:black;stroke-width:1;stroke-linecap:round;stroke-linejoin:round;stroke-miterlimit:4;stroke-dasharray:none;stroke-dashoffset:0;stroke-opacity:1"
+           id="rect2843"
+           width="184.85793"
+           height="39.395935"
+           x="63.134491"
+           y="475.44327" />
+        <text
+           xml:space="preserve"
+           style="font-size:12px;font-style:normal;font-weight:normal;fill:black;fill-opacity:1;stroke:none;stroke-width:1px;stroke-linecap:butt;stroke-linejoin:miter;stroke-opacity:1;font-family:Times New Roman"
+           x="75.230644"
+           y="498.35123"
+           id="text2847"><tspan
+             sodipodi:role="line"
+             id="tspan2849"
+             x="75.230644"
+             y="498.35123"
+             style="font-family:Courier">src/hello.c</tspan></text>
+      </g>
+      <path
+         inkscape:connection-end="#g2831"
+         inkscape:connection-start="#g2907"
+         inkscape:connector-type="polyline"
+         id="path2962"
+         d="M 248.49242,495.37535 L 311.46959,495.53401"
+         style="fill:none;fill-opacity:0.75;fill-rule:evenodd;stroke:black;stroke-width:1px;stroke-linecap:butt;stroke-linejoin:miter;marker-end:url(#Arrow1Mend);stroke-opacity:1" />
+    </g>
+    <text
+       xml:space="preserve"
+       style="font-size:12px;font-style:normal;font-weight:normal;fill:black;fill-opacity:1;stroke:none;stroke-width:1px;stroke-linecap:butt;stroke-linejoin:miter;stroke-opacity:1;font-family:Times New Roman"
+       x="96.476799"
+       y="373.96353"
+       id="text3216"><tspan
+         sodipodi:role="line"
+         id="tspan3218"
+         x="96.476799"
+         y="373.96353">Working directory</tspan></text>
+    <text
+       xml:space="preserve"
+       style="font-size:12px;font-style:normal;font-weight:normal;fill:black;fill-opacity:1;stroke:none;stroke-width:1px;stroke-linecap:butt;stroke-linejoin:miter;stroke-opacity:1;font-family:Times New Roman"
+       x="344.92493"
+       y="373.96353"
+       id="text3228"><tspan
+         sodipodi:role="line"
+         id="tspan3230"
+         x="344.92493"
+         y="373.96353">Repository</tspan></text>
+  </g>
+</svg>