3
<title>Subversion Best Practices</title>
9
<h1>Subversion Best Practices</h1>
12
<p>This is a quick set of guidelines for making the best use of
13
Subversion in your day-to-day software development work.</p>
16
<h2>Use a sane repository layout</h2>
18
<p>There are many ways to lay out your repository. Because branches
19
and tags are ordinary directories, you'll need to account for them in
20
your repository structure.</p>
22
<p>The Subversion project officially recommends the idea of a "project
23
root", which represents an anchoring point for a project. A "project
24
root" contains exactly three subdirectories: <tt>/trunk</tt>,
25
<tt>/branches</tt>, and <tt>/tags</tt>. A repository may contain
26
only one project root, or it may contain a number of them.</p>
28
<p><em>Book reference:</em><a
29
href="http://svnbook.red-bean.com/svnbook/ch05s04.html#svn-ch-5-sect-6.1">Choosing
30
a Repository Layout</a>.</p>
34
<!-- =================================================== -->
36
<h2>Commit logical changesets</h2>
38
<p>When you commit a change to the repository, make sure your change
39
reflects a single purpose: the fixing of a specific bug, the addition
40
of a new feature, or some particular task. Your commit will create a
41
new revision number which can forever be used as a "name" for the
42
change. You can mention this revision number in bug databases, or use
43
it as an argument to <tt>svn merge</tt> should you want to undo the
44
change or port it to another branch.</p>
46
<p><em>Book reference:</em> "Subversion and Changesets" sidebar,
48
href="http://svnbook.red-bean.com/svnbook/ch04s03.html">chapter
51
<!-- =================================================== -->
53
<h2>Use the issue-tracker wisely</h2>
55
<p>Try to create as many two-way links between Subversion changesets
56
and your issue-tracking database as possible:</p>
59
<li>If possible, refer to a specific issue ID in every commit log message.</li>
60
<li>When appending information to an issue (to describe progress, or
61
to close the issue) name the revision number(s) responsible
65
<!-- =================================================== -->
67
<h2>Track merges manually</h2>
69
<p>When committing the result of a merge, be sure to write a
70
descriptive log message that explains what was merged, something
73
<pre>Merged revisions 3490:4120 of /branches/foobranch to /trunk.</pre>
75
<p><em>Book reference:</em> <a
76
href="http://svnbook.red-bean.com/svnbook/ch04s03.html#svn-ch-4-sect-3.2">Tracking
77
merges manually</a>, and <a
78
href="http://svnbook.red-bean.com/svnbook/ch04s04.html#svn-ch-4-sect-4.1">Merging a whole branch to another</a>.</p>
80
<!-- =================================================== -->
82
<h2>Understand mixed-revision working copies</h2>
84
<p>Your working copy's directories and files can be at different
85
"working" revisions: this is a deliberate feature which allows you to
86
mix and match older versions of things with newer ones. But there are
87
few facts you must be aware of:</p>
91
<li>After every <tt>svn commit</tt>, your working copy has mixed
92
revisions. The things you just committed are now at the HEAD
93
revision, and everything else is at an older revision.</li>
95
<li>Certain commits are disallowed:
97
<li>You cannot commit the deletion of a file or directory which
98
doesn't have a working revision of HEAD.</li>
99
<li>You cannot commit a property change to a directory which
100
doesn't have a working revision of HEAD.</li>
104
<li><tt>svn update</tt> will bring your entire working copy to one
105
working revision, and is the typical solution to the
106
problems mentioned in point #2.</li>
109
<p><em>Book reference:</em> <a
110
href="http://svnbook.red-bean.com/svnbook/ch02s03.html#svn-ch-2-sect-3.4">The
111
limitation of mixed revisions</a>.</p>
114
<!-- =================================================== -->
116
<h2>Be patient with large files</h2>
118
<p>A nice feature of Subversion is that by design, there is no limit
119
to the size of files it can handle. Files are sent "streamily" in
120
both directions between Subversion client and server, using a small,
121
constant amount of memory on each side of the network.</p>
123
<p>Of course, there are a number of practical issues to consider.
124
While there's no need to worry about files in the kilobyte-sized range
125
(e.g. typical source-code files), committing larger files can take a
126
tremendous amount of both time and space (e.g. files that are dozens
127
or hundreds of megabytes large.)</p>
129
<p>To begin with, remember that your Subversion working copy stores
130
pristine copies of all version-controlled files in the
131
<tt>.svn/text-base/</tt> area. This means that your working copy
132
takes up at least twice as much disk space as the original dataset.
133
Beyond that, the Subversion client follows a (currently unadjustable)
134
algorithm for committing files:</p>
137
<li>Copies the file to <tt>.svn/tmp/</tt> <em>(can take a while,
138
and temporarily uses extra disk space)</em>)</li>
140
<li>Performs a binary diff between the tmpfile and the pristine
141
copy, or between the tmpfile and an empty-file if newly
142
added. <em>(can take a very long time to compute, even
143
though only a small amount of data might ultimately be sent
144
over the network)</em></li>
146
<li>Sends the diff to the server, then moves the tmpfile into
147
<tt>.svn/text-base/</tt></li>
150
<p>So while there's no theoretical limit to the size of your files,
151
you'll need to be aware that very large files may require quite a bit
152
of patient waiting while your client chugs away. You can rest
153
assured, however, that unlike CVS, your large files won't incapacitate
154
the server or affect other users.</p>
156
<!-- =================================================== -->
158
<h2>Work around commands that don't understand copies/renames</h2>
160
<p>When a file or directory is copied or renamed, the Subversion repository
161
tracks that history. Unfortunately in Subversion 1.0, the only client
162
subcommand which actually takes advantage of this feature is <tt>svn
163
log</tt>. A number of other commands (such as <tt>svn diff</tt> and
164
<tt>svn cat</tt>) ought to be automatically following rename-history,
165
but aren't doing so yet.</p>
167
<p>In all of these cases, a basic workaround is to use <tt>'svn log
168
-v'</tt> to discover the proper path within the older revision.</p>
170
<p>For example, suppose you copied <tt>/trunk</tt> to
171
<tt>/branches/mybranch</tt> in revision 200, and then committed some
172
changes to <tt>/branches/mybranch/foo.c</tt> in subsequent revisions.
173
Now you'd like to compare revisions 80 and 250 of the file.</p>
175
<p>If you have a working copy of the branch and run <tt>svn diff
176
-r80:250 foo.c</tt>, you'll see an error about
177
<tt>/branches/mybranch/foo.c</tt> not existing in revision 80. To
178
remedy, you would run <tt>svn log -v</tt> on your branch or file to
179
discover that it was named <tt>/trunk/foo.c</tt> prior to revision 200,
180
and then compare the two URLs directly:</p>
183
$ svn diff http://.../trunk/foo.c@80 \
184
http://.../branches/mybranch/foo.c@200
189
<!-- =================================================== -->
191
<h2>Know when to create branches</h2>
193
<p>This is a hotly debated question, and it really depends on the
194
culture of your software project. Rather than prescribe a universal
195
policy, we'll describe three common ones here.</p>
197
<h3>The Never-Branch system</h3>
199
<p>(Often used by nascent projects that don't yet have runnable code.)</p>
202
<li>Users commit their day-to-day work on <tt>/trunk</tt>.</li>
203
<li>Occasionally <tt>/trunk</tt> "breaks" (doesn't compile, or fails
204
functional tests) when a user begins to commit a series of complicated
208
<p><em>Pros:</em> Very easy policy to follow. New developers have low
209
barrier to entry. Nobody needs to learn how to branch or merge.</p>
211
<p><em>Cons:</em> Chaotic development, code could be unstable at any
214
<p>A side note: this sort of development is a bit less risky in
215
Subversion than in CVS. Because Subversion commits are atomic, it's
216
not possible for a checkout or update to receive a "partial" commit
217
while somebody else is in the process of committing.</p>
220
<h3>The Always-Branch system</h3>
222
<p>(Often used by projects that favor heavy management and supervision.)</p>
225
<li>Each user creates/works on a private branch for <em>every</em> coding task.
227
<li>When coding is complete, someone (original coder, peer, or
228
manager) reviews all private branch changes and merges them to
229
<tt>/trunk</tt>.</li>
232
<p><em>Pros:</em> <tt>/trunk</tt> is guaranteed to be
233
<em>extremely</em> stable at all times. </p>
235
<p><em>Cons:</em> Coders are artificially isolated from each other,
236
possibly creating more merge conflicts than necessary.
237
Requires users to do lots of extra merging.</p>
240
<h3>The Branch-When-Needed system</h3>
242
<p>(This is the system used by the Subversion project.)
245
<li>Users commit their day-to-day work on <tt>/trunk</tt>.</li>
247
<li>Rule #1: <tt>/trunk</tt> must compile and pass regression tests at
248
all times. Committers who violate this rule are publically
251
<li>Rule #2: a single commit (changeset) must not be so large
252
so as to discourage peer-review.</li>
254
<li>Rule #3: if rules #1 and #2 come into conflict (i.e. it's
255
impossible to make a series of small commits without disrupting the
256
trunk), then the user should create a branch and commit a series of
257
smaller changesets there. This allows peer-review without disrupting
258
the stability of <tt>/trunk</tt>.</li>
262
<p><em>Pros:</em> <tt>/trunk</tt> is guaranteed to be stable at all
263
times. The hassle of branching/merging is somewhat rare.</p>
265
<p><em>Cons:</em> Adds a bit of burden to users' daily work:
266
they must compile and test before every commit.</p>
272
Mapping CVS tasks to SVN tasks
273
==============================
275
This section is just a re-indexing of topics covered in the book,
276
for people who prefer to learn from the "bottom up" rather than "top down".
277
It shows some common CVS operations, and then the equivalent SVN operation,
278
followed by a link to the book which explains more.
283
* Checking out a working copy.
285
* Seeing your changes.
287
* Undoing your changes.
289
* Resolving a conflict.
291
* Adding binary files.
293
* Activating keyword expansion and/or EOL translation.
298
* Creating a tag from a working copy
300
* Creating a remote tag
302
* Seeing all of a project's tags
306
* Seeing the logs between two tags
313
* Creating a branch and switching to it
315
* Finding the beginning of a branch
317
* Merging a branch to trunk, or vice versa
b'\\ No newline at end of file'
added
removed
doc/user/svn-best-practices.html
