hgbook

annotate en/concepts.tex @ 97:659fa1a2c628

find changesets by author, revision, files, or words in the commit message
More text.
author Bryan O'Sullivan <bos@serpentine.com>
date Fri Oct 13 15:48:44 2006 -0700 (2006-10-13)
parents
children e0b961975c5e
rev   line source
jeffpc@56 1 \chapter{Basic Concepts}
jeffpc@56 2 \label{chap:concepts}
jeffpc@56 3
jeffpc@56 4 This chapter introduces some of the basic concepts behind distributed
jeffpc@56 5 version control systems such as Mercurial.
jeffpc@56 6
jeffpc@56 7 \section{Repository}
jeffpc@56 8 \label{sec:concepts:repo}
jeffpc@56 9 The repository is a directory where Mercurial stores the history for the
jeffpc@56 10 files under revision control.
jeffpc@56 11
jeffpc@56 12 \subsection{Where?}
jeffpc@56 13 % where is this repository you speak of?
jeffpc@56 14 XXX
jeffpc@56 15
jeffpc@56 16 \subsection{How?}
jeffpc@56 17 % How are the changes stored?
jeffpc@56 18 XXX
jeffpc@56 19
jeffpc@56 20 \subsection{Structure}
jeffpc@56 21 \label{sec:concepts:structure}
jeffpc@56 22 % What's the structure of the repository?
jeffpc@56 23 A typical Mercurial repository is a directory which contains a checked out
jeffpc@56 24 working copy (see section~\ref{sec:concepts:workingcopy}) as well as
jeffpc@56 25 \sdirname{.hg} directory. Figure~\ref{ex:concepts:dirlist} shows the
jeffpc@56 26 contents of a freshly created repository. This repository does not contain
jeffpc@56 27 any revisions. Let's take a look at a repository that has history for
jeffpc@56 28 several files.
jeffpc@56 29 Figure~\ref{ex:concepts:dirlist2} shows the contents of a repository keeping
jeffpc@56 30 history on two files. We see the checked out copies of the files
jeffpc@56 31 \filename{foo} and \filename{bar}, as well as the files containing their
jeffpc@56 32 histories \filename{foo.i} and \filename{bar.i}, respectively. Additionally,
jeffpc@56 33 we see the \filename{changelog.i} and \filename{00manifest.i} files. These
jeffpc@56 34 contain the repository-wide revision data, such as the commit message, and
jeffpc@56 35 the list of files in the repository during the commit.
jeffpc@56 36
jeffpc@56 37 \begin{figure}[ht]
jeffpc@56 38 \interaction{concepts.dirlist}
jeffpc@56 39 \caption{Contents of a freshly created repository}
jeffpc@56 40 \label{ex:concepts:dirlist}
jeffpc@56 41 \end{figure}
jeffpc@56 42
jeffpc@56 43 \begin{figure}[ht]
jeffpc@56 44 \interaction{concepts.dirlist2}
jeffpc@56 45 \caption{Contents of a repository tracking two files}
jeffpc@56 46 \label{ex:concepts:dirlist2}
jeffpc@56 47 \end{figure}
jeffpc@56 48
jeffpc@56 49 \subsection{hgrc}
jeffpc@56 50 % .hg/hgrc
jeffpc@56 51 XXX
jeffpc@56 52
jeffpc@56 53 \subsection{Creating a Repository}
jeffpc@56 54 % hg init
jeffpc@56 55 Creating a repository is quick and painless. One uses the \hgcmd{init}
jeffpc@56 56 command as figure~\ref{ex:concepts:hginit} demonstrates. The one argument
jeffpc@56 57 passed to the \hgcmd{init} command is the name of the repository. The name
jeffpc@56 58 can be any string usable as a directory name.
jeffpc@56 59
jeffpc@56 60 \begin{caution}
jeffpc@56 61 If you do not specify a name of the repository, the current working
jeffpc@56 62 directory will be used instead.
jeffpc@56 63 \end{caution}
jeffpc@56 64
jeffpc@56 65 \begin{figure}[ht]
jeffpc@56 66 \interaction{concepts.hginit}
jeffpc@56 67 \caption{Creating a new repository}
jeffpc@56 68 \label{ex:concepts:hginit}
jeffpc@56 69 \end{figure}
jeffpc@56 70
jeffpc@56 71 \subsection{Remote Repositories}
jeffpc@56 72 \label{sec:concepts:remoterepo}
jeffpc@56 73 In addition to repositories stored on the local file system, Mercurial
jeffpc@56 74 supports so called \emph{remote repositories}. These remote repositories
jeffpc@56 75 can be accessed via several different methods. See
jeffpc@56 76 section~\ref{sec:XXX:remotesetup} for instructions how to set up remote
jeffpc@56 77 repositories.
jeffpc@56 78 % XXX: reference the proper section!
jeffpc@56 79
jeffpc@56 80 \subsubsection{SSH}
jeffpc@56 81 \label{sec:concepts:remoterepo:ssh}
jeffpc@56 82 Mercurial can use \command{ssh} to send and receive changes. The remote
jeffpc@56 83 repository is identified by an URL. The basic format for the URL is:
jeffpc@56 84
jeffpc@56 85 \begin{verbatim}
jeffpc@56 86 ssh://[user@]host/path
jeffpc@56 87 \end{verbatim}
jeffpc@56 88
jeffpc@56 89 Where \cmdargs{user} is optional, and the \cmdargs{path} is path to the
jeffpc@56 90 repository --- either an absolute or relative to the user's home directory
jeffpc@56 91 --- on the remote host with hostname: \cmdargs{host}.
jeffpc@56 92
jeffpc@56 93 \begin{note}
jeffpc@56 94 If the path for the remote repository is absolute there will be two
jeffpc@56 95 consecutive slashes. E.g., if the remote path is \dirname{/repos/hgbook},
jeffpc@56 96 the URL would look something like the following:
jeffpc@56 97
jeffpc@56 98 \begin{verbatim}
jeffpc@56 99 ssh://someuser@remotebox//repos/hgbook
jeffpc@56 100 \end{verbatim}
jeffpc@56 101
jeffpc@56 102 Relative paths have only one slash and are relative to the user's home
jeffpc@56 103 directory.
jeffpc@56 104 \end{note}
jeffpc@56 105
jeffpc@56 106 \subsubsection{HTTP \& HTTPS}
jeffpc@56 107 \label{sec:concepts:remoterepo:http}
jeffpc@56 108 The other protocol supported is HTTP as well as HTTPS. The repository URL
jeffpc@56 109 is very much like that of the \command{ssh}.
jeffpc@56 110
jeffpc@56 111 \begin{verbatim}
jeffpc@56 112 http://[user@]remotebox/path
jeffpc@56 113 \end{verbatim}
jeffpc@56 114
jeffpc@56 115 Just as before, the username is optional.
jeffpc@56 116 % XXX: is it optional for both push & pull or just for pull?
jeffpc@56 117 This time however, the path is relative to the HTTP server root.
jeffpc@56 118
jeffpc@56 119 \section{Working Copy}
jeffpc@56 120 \label{sec:concepts:workingcopy}
jeffpc@56 121 XXX
jeffpc@56 122
jeffpc@56 123 \section{Revisions}
jeffpc@56 124 \label{sec:concepts:revs}
jeffpc@56 125 XXX
jeffpc@56 126
jeffpc@56 127 %%% Local Variables:
jeffpc@56 128 %%% mode: latex
jeffpc@56 129 %%% TeX-master: "00book"
jeffpc@56 130 %%% End:
jeffpc@56 131