jeffpc@56: \chapter{Basic Concepts}
jeffpc@56: \label{chap:concepts}
jeffpc@56: 
jeffpc@56: This chapter introduces some of the basic concepts behind distributed
jeffpc@56: version control systems such as Mercurial.
jeffpc@56: 
jeffpc@56: \section{Repository}
jeffpc@56: \label{sec:concepts:repo}
jeffpc@56: The repository is a directory where Mercurial stores the history for the
jeffpc@56: files under revision control.
jeffpc@56: 
jeffpc@56: \subsection{Where?}
jeffpc@56: % where is this repository you speak of?
jeffpc@56: XXX
jeffpc@56: 
jeffpc@56: \subsection{How?}
jeffpc@56: % How are the changes stored?
jeffpc@56: XXX
jeffpc@56: 
jeffpc@56: \subsection{Structure}
jeffpc@56: \label{sec:concepts:structure}
jeffpc@56: % What's the structure of the repository?
jeffpc@56: A typical Mercurial repository is a directory which contains a checked out
jeffpc@56: working copy (see section~\ref{sec:concepts:workingcopy}) as well as
jeffpc@56: \sdirname{.hg} directory.  Figure~\ref{ex:concepts:dirlist} shows the
jeffpc@56: contents of a freshly created repository.  This repository does not contain
jeffpc@56: any revisions. Let's take a look at a repository that has history for
jeffpc@56: several files.
jeffpc@56: Figure~\ref{ex:concepts:dirlist2} shows the contents of a repository keeping
jeffpc@56: history on two files.  We see the checked out copies of the files
jeffpc@56: \filename{foo} and \filename{bar}, as well as the files containing their
jeffpc@56: histories \filename{foo.i} and \filename{bar.i}, respectively. Additionally,
jeffpc@56: we see the \filename{changelog.i} and \filename{00manifest.i} files. These
jeffpc@56: contain the repository-wide revision data, such as the commit message, and
jeffpc@56: the list of files in the repository during the commit.
jeffpc@56: 
jeffpc@56: \begin{figure}[ht]
jeffpc@56:   \interaction{concepts.dirlist}
jeffpc@56:   \caption{Contents of a freshly created repository}
jeffpc@56:   \label{ex:concepts:dirlist}
jeffpc@56: \end{figure}
jeffpc@56: 
jeffpc@56: \begin{figure}[ht]
jeffpc@56:   \interaction{concepts.dirlist2}
jeffpc@56:   \caption{Contents of a repository tracking two files}
jeffpc@56:   \label{ex:concepts:dirlist2}
jeffpc@56: \end{figure}
jeffpc@56: 
jeffpc@56: \subsection{hgrc}
jeffpc@56: % .hg/hgrc
jeffpc@56: XXX
jeffpc@56: 
jeffpc@56: \subsection{Creating a Repository}
jeffpc@56: % hg init
jeffpc@56: Creating a repository is quick and painless.  One uses the \hgcmd{init}
jeffpc@56: command as figure~\ref{ex:concepts:hginit} demonstrates.  The one argument
jeffpc@56: passed to the \hgcmd{init} command is the name of the repository. The name
jeffpc@56: can be any string usable as a directory name.
jeffpc@56: 
jeffpc@56: \begin{caution}
jeffpc@56: If you do not specify a name of the repository, the current working
jeffpc@56: directory will be used instead.
jeffpc@56: \end{caution}
jeffpc@56: 
jeffpc@56: \begin{figure}[ht]
jeffpc@56:   \interaction{concepts.hginit}
jeffpc@56:   \caption{Creating a new repository}
jeffpc@56:   \label{ex:concepts:hginit}
jeffpc@56: \end{figure}
jeffpc@56: 
jeffpc@56: \subsection{Remote Repositories}
jeffpc@56: \label{sec:concepts:remoterepo}
jeffpc@56: In addition to repositories stored on the local file system, Mercurial
jeffpc@56: supports so called \emph{remote repositories}.  These remote repositories
jeffpc@56: can be accessed via several different methods.  See
jeffpc@56: section~\ref{sec:XXX:remotesetup} for instructions how to set up remote
jeffpc@56: repositories.
jeffpc@56: % XXX: reference the proper section!
jeffpc@56: 
jeffpc@56: \subsubsection{SSH}
jeffpc@56: \label{sec:concepts:remoterepo:ssh}
jeffpc@56: Mercurial can use \command{ssh} to send and receive changes. The remote
jeffpc@56: repository is identified by an URL. The basic format for the URL is:
jeffpc@56: 
jeffpc@56: \begin{verbatim}
jeffpc@56: ssh://[user@]host/path
jeffpc@56: \end{verbatim}
jeffpc@56: 
jeffpc@56: Where \cmdargs{user} is optional, and the \cmdargs{path} is path to the
jeffpc@56: repository --- either an absolute or relative to the user's home directory
jeffpc@56: --- on the remote host with hostname: \cmdargs{host}.
jeffpc@56: 
jeffpc@56: \begin{note}
jeffpc@56: If the path for the remote repository is absolute there will be two
jeffpc@56: consecutive slashes.  E.g., if the remote path is \dirname{/repos/hgbook},
jeffpc@56: the URL would look something like the following:
jeffpc@56: 
jeffpc@56: \begin{verbatim}
jeffpc@56: ssh://someuser@remotebox//repos/hgbook
jeffpc@56: \end{verbatim}
jeffpc@56: 
jeffpc@56: Relative paths have only one slash and are relative to the user's home
jeffpc@56: directory.
jeffpc@56: \end{note}
jeffpc@56: 
jeffpc@56: \subsubsection{HTTP \& HTTPS}
jeffpc@56: \label{sec:concepts:remoterepo:http}
jeffpc@56: The other protocol supported is HTTP as well as HTTPS.  The repository URL
jeffpc@56: is very much like that of the \command{ssh}.
jeffpc@56: 
jeffpc@56: \begin{verbatim}
jeffpc@56: http://[user@]remotebox/path
jeffpc@56: \end{verbatim}
jeffpc@56: 
jeffpc@56: Just as before, the username is optional.
jeffpc@56: % XXX: is it optional for both push & pull or just for pull?
jeffpc@56: This time however, the path is relative to the HTTP server root.  
jeffpc@56: 
jeffpc@56: \section{Working Copy}
jeffpc@56: \label{sec:concepts:workingcopy}
jeffpc@56: XXX
jeffpc@56: 
jeffpc@56: \section{Revisions}
jeffpc@56: \label{sec:concepts:revs}
jeffpc@56: XXX
jeffpc@56: 
jeffpc@56: %%% Local Variables: 
jeffpc@56: %%% mode: latex
jeffpc@56: %%% TeX-master: "00book"
jeffpc@56: %%% End:
jeffpc@56: