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