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