# HG changeset patch # User Josef "Jeff" Sipek # Date 1153799872 14400 # Node ID b8539d91c84d91e8beb2f4e954b77513ee8e5239 # Parent c0979ed1eabda13a76e1a441524bdb133a5d8883 Begining of concepts chapter diff -r c0979ed1eabd -r b8539d91c84d en/00book.tex --- a/en/00book.tex Sun Jul 16 00:01:43 2006 -0700 +++ b/en/00book.tex Mon Jul 24 23:57:52 2006 -0400 @@ -37,6 +37,7 @@ \include{preface} \include{intro} +\include{concepts} \include{hook} \include{mq} diff -r c0979ed1eabd -r b8539d91c84d en/99defs.tex --- a/en/99defs.tex Sun Jul 16 00:01:43 2006 -0700 +++ b/en/99defs.tex Mon Jul 24 23:57:52 2006 -0400 @@ -25,6 +25,9 @@ \newenvironment{note}% {\begin{lrbox}{\notebox}\begin{minipage}{0.7\textwidth}\textbf{Note:}\space}% {\end{minipage}\end{lrbox}\fbox{\usebox{\notebox}}} +\newenvironment{caution}% + {\begin{lrbox}{\notebox}\begin{minipage}{0.7\textwidth}\textbf{Caution:}\space}% + {\end{minipage}\end{lrbox}\fbox{\usebox{\notebox}}} \DefineVerbatimEnvironment{codesample4}{Verbatim}{frame=single,gobble=4,numbers=left,commandchars=\\\{\}} \newcommand{\interaction}[1]{\VerbatimInput[frame=single,numbers=left,commandchars=\\\{\}]{examples/#1.out}} diff -r c0979ed1eabd -r b8539d91c84d en/Makefile --- a/en/Makefile Sun Jul 16 00:01:43 2006 -0700 +++ b/en/Makefile Mon Jul 24 23:57:52 2006 -0400 @@ -7,6 +7,7 @@ 99book.bib \ 99defs.tex \ build_id.tex \ + concepts.tex \ hook.tex \ intro.tex \ mq.tex \ @@ -18,6 +19,7 @@ example-sources := \ examples/run-example \ examples/hook.simple \ + examples/concepts \ examples/mq.qinit-help \ examples/mq.diff \ examples/mq.tarball \ diff -r c0979ed1eabd -r b8539d91c84d en/concepts.tex --- /dev/null Thu Jan 01 00:00:00 1970 +0000 +++ b/en/concepts.tex Mon Jul 24 23:57:52 2006 -0400 @@ -0,0 +1,131 @@ +\chapter{Basic Concepts} +\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. + +\subsection{Where?} +% where is this repository you speak of? +XXX + +\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. + +\begin{figure}[ht] + \interaction{concepts.dirlist} + \caption{Contents of a freshly created repository} + \label{ex:concepts:dirlist} +\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 c0979ed1eabd -r b8539d91c84d en/examples/concepts --- /dev/null Thu Jan 01 00:00:00 1970 +0000 +++ b/en/examples/concepts Mon Jul 24 23:57:52 2006 -0400 @@ -0,0 +1,19 @@ +#$ name: dirlist +hg init newrepo +cd newrepo + +find . + +#$ name: +echo "a line of text" > foo +echo "another life of text" > bar +hg commit -A -m "Some files" + +#$ name: dirlist2 +find . + +#$ name: +cd .. + +#$ name: hginit +hg init reponame