1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94
95
96
97
98
99
100
101
102
103
104
105
106
107
108
109
110
111
112
113
114
115
116
117
118
119
120
121
122
123
124
125
126
127
128
129
130
131
132
133
134
135
136
137
138
139
140
141
142
143
144
145
146
147
148
149
150
151
152
153
154
155
156
157
158
159
160
161
162
163
164
165
166
167
168
169
170
171
172
173
174
175
176
177
178
179
180
181
182
183
184
185
186
187
188
189
190
191
192
193
194
195
196
197
198
199
200
201
202
203
204
205
206
207
208
209
210
211
212
213
214
215
216
217
218
|
<chapter id="client">
<title>Client — How the client works</title>
<simplesect>
<para>The Subversion client is built on three libraries. One operates
strictly on the working copy and does not talk to the repository.
Another talks to the repository but never changes the working copy. The
third library uses the first two to provide operations such as
<literal>commit</literal> and <literal>update</literal> –
operations which need to both talk to the repository and change the
working copy.</para>
<para>The initial client is a Unix-style command-line tool (like standard
CVS), but it should be easy to write a GUI client as well, based on the
same libraries. The libraries capture the core Subversion functionality,
segregating it from user interface concerns.</para>
<para>This chapter describes the libraries, and the physical layout of
working copies.</para>
</simplesect>
<sect1 id="client.wc">
<title>Working copies and the working copy library</title>
<para>Working copies are client-side directory trees containing both
versioned data and Subversion administrative files. The functions in the
working copy management library are the only functions in Subversion
which operate on these trees.</para>
<sect2 id="client.wc.layout">
<title>The layout of working copies</title>
<para>This section gives an overview of how
working copies are arranged physically, but is not a full specification
of working copy layout.</para>
<para>As with CVS, Subversion working copies are simply directory trees
with special administrative subdirectories, in this case named ".svn"
instead of "CVS":</para>
<programlisting>
myproj
/ | \
_____________/ | \______________
/ | \
.svn src doc
___/ | \___ /|\ ___/ \___
| | | / | \ | |
base ... ... / | \ myproj.texi .svn
/ | \ ___/ | \___
____/ | \____ | | |
| | | base ... ...
.svn foo.c bar.c |
___/ | \___ |
| | | |
base ... ... myproj.texi
___/ \___
| |
foo.c bar.c
</programlisting>
<para>Each <filename>dir/.svn/</filename> directory records the files in
<filename>dir</filename>, their revision numbers and property lists,
pristine revisions of all the files (for client-side delta generation),
the repository from which <filename>dir</filename> came, and any local
changes (such as uncommitted adds, deletes, and renames) that affect
<filename>dir</filename>.</para>
<para>Although it would often be possible to deduce certain information
(such as the original repository) by examining parent directories, this
is avoided in favor of making each directory be as much a
self-contained unit as possible.</para>
<para>For example, immediately after a checkout the administrative
information for the entire working tree <emphasis>could</emphasis> be
stored in one top-level file. But subdirectories instead keep track of
their own revision information. This would be necessary anyway once
the user starts committing new revisions for particular files, and it
also makes it easier for the user to prune a big, complete tree into a
small subtree and still have a valid working copy.</para>
<para>The <filename>.svn</filename> subdir contains:</para>
<itemizedlist mark="bullet">
<listitem><para>A <filename>format</filename> file, which indicates
which version of the working copy adm format this is (so future
clients can be backwards compatibleeasily).</para></listitem>
<listitem><para>A <filename>text-base</filename> directory,
containing the pristine repository revisions of the files in the
corresponding working directory</para></listitem>
<listitem><para>An <filename>entries</filename> file, which holds
revision numbers and other information for this directory and its
files, and records the presence of subdirs. It also contains the
repository URLs that each file and directory came from. It may
help to think of this file as the functional equivalent of the
<filename>CVS/Entries</filename> file.</para></listitem>
<listitem><para>A <filename>props</filename> directory, containing
property names and values for each file in the working
directory.</para></listitem>
<listitem><para>A <filename>prop-base</filename> directory,
containing pristine property names and values for each file in
the working directory.</para></listitem>
<listitem><para>A <filename>dir-props</filename> file, recording
properties for this directory.</para></listitem>
<listitem><para>A <filename>dir-prop-base</filename> file, recording
pristine properties for thisdirectory.</para></listitem>
<listitem><para>A <filename>lock</filename> file, whose presence
implies that some client is currently operating on the
administrative area.</para></listitem>
<listitem><para>A <filename>tmp</filename> directory, for holding
scratch-work and helping make working copy operations more
crash-proof.</para></listitem>
<listitem><para>A <filename>log</filename> file. If present,
indicates a list of actions that need to be taken to complete a
working-copy-operation that is still "in
progress".</para></listitem>
</itemizedlist>
<para>You can read much more about these files in the file
<filename>subversion/libsvn_wc/README</filename>.</para>
</sect2>
<sect2 id="client.wc.library">
<title>The working copy management library</title>
<itemizedlist mark="bullet">
<listitem><para><emphasis role="bold">Requires:</emphasis>
<itemizedlist mark="minus">
<listitem><para>a working copy</para></listitem>
</itemizedlist>
</para></listitem>
<listitem><para><emphasis role="bold">Provides:</emphasis>
<itemizedlist mark="minus">
<listitem><para>ability to manipulate the working copy's versioned
data</para></listitem>
<listitem><para>ability to manipulate the working copy's
administrative files</para></listitem>
</itemizedlist>
</para></listitem>
</itemizedlist>
<para>This library performs "offline" operations on the working copy, and
lives in <filename>subversion/libsvn_wc/</filename>.</para>
<para>The API for <replaceable>libsvn_wc</replaceable> is always
evolving; please read the header file for a detailed description:
<filename>subversion/include/svn_wc.h</filename>.</para>
</sect2>
</sect1>
<sect1 id="client.libsvn_ra">
<title>The repository access library</title>
<itemizedlist mark="bullet">
<listitem><para><emphasis role="bold">Requires:</emphasis>
<itemizedlist mark="minus">
<listitem><para>network access to a Subversion
server</para></listitem>
</itemizedlist>
</para></listitem>
<listitem><para><emphasis role="bold">Provides:</emphasis>
<itemizedlist mark="minus">
<listitem><para>the ability to interact with a
repository</para></listitem>
</itemizedlist>
</para></listitem>
</itemizedlist>
<para>This library performs operations involving communication with the
repository.</para>
<para>The interface defined in
<filename>subversion/include/svn_ra.h</filename> provides a uniform
interface to both local and remote repository access.</para>
<para>Specifically, <replaceable>libsvn_ra_dav</replaceable> will provide
this interface and speak to repositories using DAV requests. At some
future point, another library <replaceable>libsvn_ra_local</replaceable>
will provide the same interface – but will link directly to the
filesystem library for accessing local disk repositories.</para>
</sect1>
<sect1 id="client.libsvn_client">
<title>The client operation library</title>
<itemizedlist mark="bullet">
<listitem><para><emphasis role="bold">Requires:</emphasis>
<itemizedlist mark="minus">
<listitem><para>the working copy management library</para></listitem>
<listitem><para>a repository access library</para></listitem>
</itemizedlist>
</para></listitem>
<listitem><para><emphasis role="bold">Provides:</emphasis>
<itemizedlist mark="minus">
<listitem><para>all client-side Subversion commands</para></listitem>
</itemizedlist>
</para></listitem>
</itemizedlist>
<para>These functions correspond to user-level client commands. In theory,
any client interface (command-line, GUI, emacs, Python, etc.) should be
able to link to <replaceable>libsvn_client</replaceable> and have the
ability to act as a full-featured Subversion client.</para>
<para>Again, the detailed API can be found in
<filename>subversion/include/svn_client.h</filename>.</para>
</sect1>
</chapter>
|
