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
|