| blob | d7f74c7f4369f85ad77adbbf7c3c66e33721c635 |
4 <head>
13 </head>
15 <body>
20 </div>
23 substantial update was in October 2002 (r3377). However, people often come
31 <ol>
37 <ol>
42 </ol>
44 </ol>
47 <ol>
52 Developments</a></li>
55 </ol>
58 <ol>
62 </ol>
65 <ol>
70 <li><a href="#deltas.serializing-via-editor">Serializing Deltas via the "Editor" Interface</a></li>
71 </ol>
74 <ol>
76 <ol>
79 </ol>
83 </ol>
86 <ol>
89 </ol>
92 <ol>
94 <ol>
98 <ol>
102 </ol>
105 </ol>
108 </ol>
111 </ol>
112 </div>
114 <!--
115 ================================================================
116 Copyright (c) 1999-2004 CollabNet. All rights reserved.
118 Redistribution and use in source and binary forms, with or without
119 modification, are permitted provided that the following conditions are
120 met:
122 1. Redistributions of source code must retain the above copyright
123 notice, this list of conditions and the following disclaimer.
125 2. Redistributions in binary form must reproduce the above copyright
126 notice, this list of conditions and the following disclaimer in the
127 documentation and/or other materials provided with the distribution.
129 3. The end-user documentation included with the redistribution, if
130 any, must include the following acknowledgment: "This product includes
131 software developed by CollabNet (http://www.Collab.Net/)."
132 Alternately, this acknowledgment may appear in the software itself, if
133 and wherever such third-party acknowledgments normally appear.
135 4. The hosted project names must not be used to endorse or promote
136 products derived from this software without prior written
137 permission. For written permission, please contact info@collab.net.
139 5. Products derived from this software may not use the "Tigris" name
140 nor may "Tigris" appear in their names without prior written
141 permission of CollabNet.
143 THIS SOFTWARE IS PROVIDED ``AS IS'' AND ANY EXPRESSED OR IMPLIED
144 WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE IMPLIED WARRANTIES OF
145 MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE ARE DISCLAIMED.
146 IN NO EVENT SHALL COLLABNET OR ITS CONTRIBUTORS BE LIABLE FOR ANY
147 DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR CONSEQUENTIAL
148 DAMAGES (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE
149 GOODS OR SERVICES; LOSS OF USE, DATA, OR PROFITS; OR BUSINESS
150 INTERRUPTION) HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER
151 IN CONTRACT, STRICT LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR
152 OTHERWISE) ARISING IN ANY WAY OUT OF THE USE OF THIS SOFTWARE, EVEN IF
153 ADVISED OF THE POSSIBILITY OF SUCH DAMAGE.
155 ====================================================================
157 This software consists of voluntary contributions made by many
158 individuals on behalf of CollabNet.
159 -->
172 <p>The goal of the Subversion project is to write a version control
173 system that takes over CVS's current and future user base
175 (If you're not familiar with CVS or its shortcomings, then
177 . The first release
178 has all the major features of CVS, plus certain new features that CVS
179 users often wish they had. In general, Subversion works like CVS, except
180 where there's a compelling reason to be different.</p>
184 <ul>
185 <li><p>It versions directories, file-metadata, renames, copies
186 and removals/resurrections. In other words, Subversion records the
187 changes users make to directory trees, not just changes to file
188 contents.</p></li>
190 <li><p>Tagging and branching are constant-time and
191 constant-space.</p></li>
193 <li><p>It is natively client-server, hence much more
194 maintainable than CVS. (In CVS, the client-server protocol was added
195 as an afterthought. This means that most new features have to be
196 implemented twice, or at least more than once: code for the local
197 case, and code for the client-server case.)</p></li>
199 <li><p>The repository is organized efficiently and
200 comprehensibly. (Without going into too much detail, let's just say
201 that CVS's repository structure is showing its
202 age.)</p></li>
204 <li><p>Commits are atomic. Each commit results in a single
205 revision number, which refers to the state of the entire tree. Files
206 no longer have their own revision numbers.</p></li>
208 <li><p>The locking scheme is only as strict as absolutely
209 necessary. Reads are never locked, and writes lock only the files
210 being written, for only as long as needed.</p></li>
214 <li><p>It handles binary files gracefully (experience has shown
215 that CVS's binary file handling is prone to user
216 error).</p></li>
218 <li><p>It takes advantage of the Net's experience with CVS by
219 choosing better default behaviors for certain
220 situations.</p></li>
221 </ul>
223 <p>Some of these advantages are clear and require no further discussion.
224 Others are not so obvious, and are explained in greater detail
225 below.</p>
232 <p>Full rename support means you can trace through ancestry by name
237 that file no longer exists, or has a different name now)? In Subversion,
238 both interpretations are available to the user.</p>
240 <p>(Note: we've not yet implemented this, but it wouldn't be too hard.
241 People are advocating switches to 'svn log' that cause history to be
242 traced backwards either by entity or by path.)</p>
249 <p>Historically, binary files have been problematic in CVS for two
250 unrelated reasons: keyword expansion, and line-end conversion.</p>
252 <ul>
258 gives plaintext files the appropriate line-ending conventions for the
259 working copy's platform. For example, Unix working copies use LF, but
260 Windows working copies use CRLF. (Like CVS, the Subversion
261 repository stores text files in Unix LF format).</p></li>
262 </ul>
264 <p>Both keyword substitution and line-end conversion are sensible only
265 for plain text files. CVS only recognizes two file types anyway:
266 plaintext and binary. And CVS assumes files are plain text unless you
267 tell it otherwise.</p>
269 <p>Subversion recognizes the same two types. The question is, how does
270 it determine a file's type? Experience with CVS suggests that assuming
271 text unless told otherwise is a losing strategy – people frequently
272 forget to mark images and other opaque formats as binary, then later they
273 wonder why CVS mangled their data. So Subversion will not mangle data:
274 when moving over the network, or when being stored in the repository, it
275 treats all files as binary. In the working copy, a tweakable meta-data
276 property indicates whether to treat the file as text or binary for
277 purposes of whether or not to allow contextual merging during
278 updates.</p>
280 <p>Users can turn line-end conversion on or off per file by tweaking
282 substitution by default, on the theory that if someone wants substitution
283 and isn't getting it, they'll look in the manual; but if they are getting
284 it and didn't want it, they might just be confused and not know what to
285 do. Users can turn substitution on or off per file.</p>
287 <p>Both of these changes are done on the client side; the repository
288 does not even know about them.</p>
296 errors can be customized to the appropriate human language at build-time
297 (or run time, if that's not much harder).</p>
299 <p>File names and contents may be multilingual; Subversion does not
300 assume an ASCII-only universe. For purposes of keyword expansion and
301 line-end conversion, Subversion also understands the UTF-* encodings (but
302 not necessarily all of them by the first release).</p>
309 <p>Subversion supports branching and tagging with one efficient
310 operation: `clone'. To clone a tree is to copy it, to create another
311 tree exactly like it (except that the new tree knows its ancestry
312 relationship to the old one).</p>
314 <p>At the moment of creation, a clone requires only a small, constant
315 amount of space in the repository – most of its storage is shared
316 with the original tree. If you never commit anything on the clone, then
317 it's just like a CVS tag. If you start committing on it, then it's a
318 branch. Voila! This also implies CVS's "vendor branching" feature,
319 since Subversion has real rename and directory support.</p>
330 <p>Subversion has a flexible log message policy (a small matter, but
331 one dear to our hearts).</p>
333 <p>Log messages should be a matter of project policy, not version
334 control software policy. If a user commits with no log message, then
335 Subversion defaults to an empty message. (CVS tries to require log
336 messages, but fails: we've all seen empty log messages in CVS, where
337 the user committed with deliberately empty quotes. Let's stop the
338 madness now.)</p>
347 <p>There is no need for Subversion to have every possible diff
348 mechanism built in. It can invoke a user-specified client-side diff
349 program on the two revisions of the file(s) locally.</p>
351 <p>(Note: This feature does not exist yet, but is planned for
359 <p>Subversion remembers what has already been merged in and what
360 hasn't, thereby avoiding the problem, familiar to CVS users, of
361 spurious conflicts on repeated merges.</p>
364 Tracking</a>) does not exist yet, but is planned for inclusion
374 <p>For text files, Subversion resolves conflicts similarly to CVS, by
375 folding repository changes into the working files with conflict
377 Subversion also always puts the old and new pristine repository
378 revisions into temporary files, and the pristine working copy revision
379 in another temporary file.</p>
381 <p>Thus, for any conflict, the user has four files readily at
382 hand:</p>
384 <ol>
385 <li><p>the original working copy file with local
386 mods</p></li>
389 <li><p>the merged file, with conflict
390 markers</p></li>
391 </ol>
393 <p>and in a binary file conflict, the user has all but the
394 last.</p>
396 <p>When the conflict has been resolved and the working copy is
397 committed, Subversion automatically removes the temporary pristine
398 files.</p>
400 <p>A more general solution would allow plug-in merge resolution tools
401 on the client side; but this is not scheduled for the first release).
402 Note that users can use their own merge tools anyway, since all the
403 original files are available.</p>
415 relate to each other.</p>
422 <p>Suppose you are using Subversion to manage a software project. There
423 are two things you will interact with: your working directory, and the
424 repository.</p>
427 directory tree, on your local system, containing your project's sources.
428 You can edit these files and compile your program from them in the usual
429 way. Your working directory is your own private work area: Subversion
430 never changes the files in your working directory, or publishes the
431 changes you make there, until you explicitly tell it to do so.</p>
433 <p>After you've made some changes to the files in your working
434 directory, and verified that they work properly, Subversion provides
435 commands to publish your changes to the other people working with you on
436 your project. If they publish their own changes, Subversion provides
437 commands to incorporate those changes into your working directory.</p>
439 <p>A working directory contains some extra files, created and maintained
440 by Subversion, to help it carry out these commands. In particular, these
441 files help Subversion recognize which files contain unpublished changes,
442 and which files are out-of-date with respect to others' work.</p>
444 <p>While your working directory is for your use alone, the
446 with everyone else working on the project. To publish your changes, you
447 use Subversion to put them in the repository. (What this means, exactly,
448 we explain below.) Once your changes are in the repository, others can
449 tell Subversion to incorporate your changes into their working
450 directories. In a collaborative environment like this, each user will
451 typically have their own working directory (or perhaps more than one),
452 and all the working directories will be backed by a single repository,
453 shared amongst all the users.</p>
455 <p>A Subversion repository holds a single directory tree, and records
456 the history of changes to that tree. The repository retains enough
457 information to recreate any prior state of the tree, compute the
458 differences between any two prior trees, and report the relations between
459 files in the tree — which files are derived from which other
460 files.</p>
462 <p>A Subversion repository can hold the source code for several
463 projects; usually, each project is a subdirectory in the tree. In this
464 arrangement, a working directory will usually correspond to a particular
465 subtree of the repository.</p>
469 <pre>
470 /trunk/paint/Makefile
471 canvas.c
472 brush.c
473 write/Makefile
474 document.c
475 search.c
476 </pre>
478 <p>In other words, the repository's root directory has a single
484 some subtree of the repository. If you check out
486 this:</p>
488 <pre>
489 write/Makefile
490 document.c
491 search.c
492 .svn/
493 </pre>
495 <p>This working directory is a copy of the repository's
498 information needed by Subversion, as mentioned above.</p>
502 date and original contents, Subversion can tell that you've changed the
503 file. However, Subversion does not make your changes public until you
504 explicitly tell it to.</p>
506 <p>To publish your changes, you can use Subversion's
509 <pre>
510 $ pwd
511 /home/jimb/write
512 $ ls -a
513 .svn/ Makefile document.c search.c
514 $ svn commit search.c
515 $
516 </pre>
519 to the repository; if another user checks out a working copy of
522 <p>Suppose you have a collaborator, Felix, who checked out a working
525 working copy is left unchanged; Subversion only modifies working
526 directories at the user's request.</p>
528 <p>To bring his working directory up to date, Felix can use the
530 incorporate your changes into his working directory, as well as any
531 others that have been committed since he checked it out.</p>
533 <pre>
534 $ pwd
535 /home/felix/write
536 $ ls -a
537 .svn/ Makefile document.c search.c
538 $ svn update
539 U search.c
540 $
541 </pre>
544 command indicates that Subversion updated the contents of
546 which files to update; Subversion uses the information in the
548 repository, to decide which files need to be brought up to date.</p>
550 <p>We explain below what happens when both you and Felix make changes to
551 the same file.</p>
559 publish changes to any number of files and directories as a single atomic
560 transaction. In your working directory, you can change files' contents,
561 create, delete, rename and copy files and directories, and then commit
562 the completed set of changes as a unit.</p>
564 <p>In the repository, each commit is treated as an atomic transaction:
565 either all the commit's changes take place, or none of them take place.
566 Subversion tries to retain this atomicity in the face of program crashes,
567 system crashes, network problems, and other users' actions. We may call
569 its indivisible nature.</p>
571 <p>Each time the repository accepts a transaction, this creates a new
573 revision is assigned a unique natural number, one greater than the number
574 of the previous revision. The initial revision of a freshly created
575 repository is numbered zero, and consists of an empty root
576 directory.</p>
578 <p>Since each transaction creates a new revision, with its own number,
579 we can also use these numbers to refer to transactions; transaction
582 zero.</p>
584 <p>Unlike those of many other systems, Subversion's revision numbers
585 apply to an entire tree, not individual files. Each revision number
586 selects an entire tree.</p>
588 <p>It's important to note that working directories do not always
589 correspond to any single revision in the repository; they may contain
590 files from several different revisions. For example, suppose you check
591 out a working directory from a repository whose most recent revision is
594 <pre>
595 write/Makefile:4
596 document.c:4
597 search.c:4
598 </pre>
600 <p>At the moment, this working directory corresponds exactly to revision
601 4 in the repository. However, suppose you make a change to
603 commits have taken place, your commit will create revision 5 of the
604 repository, and your working directory will look like this:</p>
606 <pre>
607 write/Makefile:4
608 document.c:4
609 search.c:5
610 </pre>
612 <p>Suppose that, at this point, Felix commits a change to
615 directory up to date, then it will look like this:</p>
617 <pre>
618 write/Makefile:6
619 document.c:6
620 search.c:6
621 </pre>
624 your working copy of that file, and your change will still be present in
627 Subversion will mark your working copy with revision 6 to indicate that
628 it is still current. So, after you do a clean update at the root of your
629 working directory, your working directory will generally correspond
630 exactly to some revision in the repository.</p>
637 <p>For each file in a working directory, Subversion records two
638 essential pieces of information:</p>
640 <ul>
641 <li><p>what revision of what repository file your working copy
644 <li><p>a timestamp recording when the local copy was last
645 updated.</p></li>
646 </ul>
648 <p>Given this information, by talking to the repository, Subversion can
649 tell which of the following four states a file is in:</p>
651 <ul>
653 The file is unchanged in the working directory, and no changes to that
654 file have been committed to the repository since its base
655 revision.</p></li>
656 <li><p><strong>Locally changed, and
657 current</strong>. The file has been changed in the working
658 directory, and no changes to that file have been committed to the
659 repository since its base revision. There are local changes that have
660 not been committed to the repository.</p></li>
661 <li><p><strong>Unchanged, and
662 out-of-date</strong>. The file has not been changed in
663 the working directory, but it has been changed in the repository. The
664 file should eventually be updated, to make it current with the
665 public revision.</p></li>
666 <li><p><strong>Locally changed, and
667 out-of-date</strong>. The file has been changed both in the
668 working directory, and in the repository. The file should be updated;
669 Subversion will attempt to merge the public changes with the local
670 changes. If it can't complete the merge in a plausible
671 way automatically, Subversion leaves it to the user to resolve the
672 conflict.</p></li>
673 </ul>
677 <h3>Locking vs. Merging - Two Paradigms of Co-operative
678 Developments</h3>
682 handling simultaneous editing by multiple users. This means that
683 Subversion does not prevent two users from making changes to the same
684 file at the same time. For example, if both you and Felix have checked
687 your working directories. Then, the following sequence of events will
688 occur:</p>
690 <ul>
691 <li><p>Suppose Felix tries to commit his changes to
693 his text will appear in the latest revision in the
694 repository.</p></li>
695 <li><p>When you attempt to commit your changes to
698 you can commit it.</p></li>
700 will try to merge Felix's changes from the repository with your local
701 changes. By default, Subversion merges as if it were applying a
702 patch: if your local changes do not overlap textually with Felix's,
703 then all is well; otherwise, Subversion leaves it to you to resolve
704 the overlapping changes. In either case, Subversion carefully
705 preserves a copy of the original pre-merge text.</p></li>
706 <li><p>Once you have verified that Felix's changes and your
707 changes have been merged correctly, you can commit the new revision
709 changes.</p></li>
710 </ul>
713 prevent others from changing a file once one person has begun working on
714 it. In our experience, merging is preferable to locks, because:</p>
716 <ul>
717 <li><p>changes usually do not conflict, so Subversion's behavior
718 does the right thing by default, while locking can interfere with
719 legitimate work;</p></li>
720 <li><p>locking can prevent conflicts within a file, but not
721 conflicts between files (say, between a C header file and another
722 file that includes it), so it doesn't really solve the problem; and
723 finally,</p></li>
724 <li><p>people often forget that they are holding locks,
725 resulting in unnecessary delays and friction.</p></li>
726 </ul>
728 <p>Of course, some kinds of files with rigid formats, like images or
729 executables, are simply not mergeable. To support this, Subversion
730 allows users to customize its merging behavior on a per-file basis.
731 Firstly, you can direct Subversion to refuse to merge changes to certain
732 files, and simply present you with the two original texts to choose from.
733 Secondly, in Subversion 1.2 and later, support for the
735 files can be designated as requiring locking.</p>
737 <p>(In the future, you may be able to direct Subversion to merge using a
738 tool which respects the semantics of specific complex file
739 formats.)</p>
746 <p>Files generally have interesting attributes beyond their contents:
747 mime-types, executable permissions, EOL styles, and so on. Subversion
748 attempts to preserve these attributes, or at least record them, when
749 doing so would be meaningful. However, different operating systems
750 support very different sets of file attributes: Windows NT supports
751 access control lists, while Linux provides only the simpler traditional
752 Unix permission bits.</p>
754 <p>In order to interoperate well with clients on many different
756 lists</strong>, a simple, general-purpose mechanism which clients
757 can use to store arbitrary out-of-band information about files.</p>
759 <p>A property list is a set of name / value pairs. A property name is
760 an arbitrary text string, expressed as a Unicode UTF-8 string,
761 canonically decomposed and ordered. A property value is an arbitrary
762 string of bytes. Property values may be of any size, but Subversion may
763 not handle very large property values efficiently. No two properties in
764 a given a property list may have the same name. Although the word `list'
765 usually denotes an ordered sequence, there is no fixed order to the
766 properties in a property list; the term `property list' is
767 historical.</p>
769 <p>Each revision number, file, directory, and directory entry in the
770 Subversion repository, has its own property list. Subversion puts these
771 property lists to several uses:</p>
773 <ul>
774 <li><p>Clients can use properties to store file attributes, as
775 described above.</p></li>
776 <li><p>The Subversion server uses properties to hold attributes
777 of its own, and allow clients to read and modify them. For example,
779 property might hold an access control list which the Subversion server
780 uses to regulate access to repository files.</p></li>
781 <li><p>Users can invent properties of their own, to store
782 arbitrary information for use by scripts, build environments, and so
783 on. Names of user properties should be URI's, to avoid conflicts
784 between organizations.</p></li>
785 </ul>
787 <p>Property lists are versioned, just like file contents. You can
788 change properties in your working directory, but those changes are not
789 visible in the repository until you commit your local changes. If you do
790 commit a change to a property value, other users will see your change
791 when they update their working directories.</p>
799 beginning of the Subversion project. This functionality probably will
801 should be reasonably solvable by recording merge data in
802 'properties'.]</p>
804 <p>Subversion defines merges the same way CVS does: to merge means to
805 take a set of previously committed changes and apply them, as a patch, to
806 a working copy. This change can then be committed, like any other
807 change. (In Subversion's case, the patch may include changes to
808 directory trees, not just file contents.)</p>
810 <p>As defined thus far, merging is equivalent to hand-editing the
811 working copy into the same state as would result from the patch
813 – it is equivalent to just editing the files, and there is no
814 record of which ancestors these particular changes came from.
815 Unfortunately, this leads to conflicts when users unintentionally merge
816 the same changes again. (Experienced CVS users avoid this problem by
817 using branch- and merge-point tags, but that involves a lot of unwieldy
818 bookkeeping.)</p>
821 sets</strong>. A revision's ancestry set is the set of all changes
822 "accounted for" in that revision. By maintaining ancestry sets, and
823 consulting them when doing merges, Subversion can detect when it would
824 apply the same patch twice, and spare users much bookkeeping. Ancestry
825 sets are stored as properties.</p>
827 <p>In the examples below, bear in mind that revision numbers usually
828 refer to changes, rather than the full contents of that revision. For
832 <p>The simplest ancestor sets are associated with linear histories. For
833 example, here's the history of a file A:</p>
835 <pre>
837 _____ _____ _____ _____ _____
838 | | | | | | | | | |
840 |_____| |_____| |_____| |_____| |_____|
842 </pre>
846 <pre>
850 </pre>
854 this will be represented with a more compact notation:</p>
856 <pre>
860 </pre>
863 postulates an entirely different revision history, of course, and the
864 global revision numbers in the diagrams will change to reflect it.)
865 Here's what the project looks like with the branch:</p>
867 <pre>
869 _____ _____ _____ _____ _____ _____
870 | | | | | | | | | | | |
872 |_____| |_____| |_____| |_____| |_____| |_____|
873 \
874 \
875 \ _____ _____ _____
876 \| | | | | |
878 |_____| |_____| |_____|
880 </pre>
883 trunk</p>
885 <pre>
887 _____ _____ _____ _____ _____ _____
888 | | | | | | | | | | | |
890 |_____| |_____| |_____| |_____| |_____| / |_____|
891 \ |
892 \ |
893 \ _____ _____ _____ /
894 \| | | | | | /
896 |_____| |_____| |_____|
898 </pre>
902 <pre>
906 </pre>
910 <pre>
914 </pre>
916 <p>(It's all right that each file's ranges seem to include non-changes;
917 this is just a notational convenience, and you can think of the
918 non-changes as either not being included, or being included but being
919 null deltas as far as that file is concerned).</p>
922 so are all changes along the A line, including both the merge and any
923 non-merge-related edits made before the commit.</p>
925 <p>Although this merge happened to include all the branch changes, that
926 needn't be the case. For example, the next time we merge the B
927 line</p>
929 <pre>
931 _____ _____ _____ _____ _____ _____ _____
932 | | | | | | | | | | | | | |
934 |_____| |_____| |_____| |_____| |_____| | |_____| | |_____|
935 \ / |
936 \ / |
937 \ _____ _____ _____ / _____ |
938 \| | | | | | / | | /
940 |_____| |_____| |_____| |_____|
942 </pre>
946 ancestry will be</p>
948 <pre>
952 </pre>
954 <p>But why limit ourselves to contiguous ranges? An ancestry set is
957 <pre>
959 _____ _____ _____ _____ _____ _____
960 | | | | | | | | | | | |
962 |_____| |_____| |_____| |_____| |_____| / |_____|
963 | /
964 | ______________________.__/
965 | / |
966 | / |
967 \ __/_ _|__
968 \ { } { }
969 \ _____ _____ _____ _____
970 \| | | | | | | |
972 |_____| |_____| |_____| |_____|
974 </pre>
977 merged into a working copy whose ancestry set (so far) is
979 ancestry set is</p>
981 <pre>
985 </pre>
988 It usually means "Merge all the changes accounted for in B's tip into A",
992 <p>Any merge, when viewed in detail, is an application of a particular
994 copy. The user-level interface may allow some of these changes to be
995 specified implicitly. For example, many merges involve a single,
996 contiguous range of changes, with one or both ends of the range easily
997 deducible from context (i.e., branch root to branch tip). These
998 inference rules are not specified here, but it should be clear in most
999 contexts how they work.</p>
1001 <p>Because each node knows its ancestors, Subversion never merges the
1002 same change twice (unless you force it to). For example, if after the
1003 above merge, you tell Subversion to merge all B changes into A,
1004 Subversion will notice that two of them have already been merged, and so
1005 merge only the other two changes, resulting in a final ancestry set
1006 of:</p>
1008 <pre>
1012 </pre>
1014 <!--
1015 Heh, what about this:
1017 B:3 adds line 3, with the text "foo".
1018 B:5 deletes line 3.
1019 B:7 adds line 3, with the text "foo".
1020 B:9 deletes line 3.
1022 The user first merges B:5 and B:9 into A. If A had that line, it goes away
1023 now, nothing more.
1025 Next, user merges B:3 and B:7 into A. The second merge must conflict.
1027 I'm not sure we need to care about this, I just thought I'd note how even
1028 merges that seem like they ought to be easily composable can still suck. :-)
1029 -->
1031 <p>This description of merging and ancestry applies to both intra- and
1032 inter-repository merges. However, inter-repository merging will probably
1033 not be implemented until a future release of Subversion.</p>
1042 <p>Subversion is conceptually divided into a number of separable
1043 layers.</p>
1045 <p>Assuming that the programmatic interface of each layer is
1046 well-defined, it is easy to customize the different parts of the system.
1047 Contributors can write new client apps, new network protocols, new server
1048 processes, new server features, and new storage back-ends.</p>
1051 where each particular interface lies.</p>
1053 <pre>
1054 +--------------------+
1055 | commandline or GUI |
1056 | client app |
1057 +----------+--------------------+----------+ <=== Client interface
1058 | Client Library |
1059 | |
1060 | +----+ |
1061 | | | |
1062 +-------+--------+ +--------------+--+----------+ <=== Network interface
1063 | Working Copy | | Remote | | Local |
1064 | Management lib | | Repos Access | | Repos |
1065 +----------------+ +--------------+ | Access |
1066 | neon | | |
1067 +--------------+ | |
1068 ^ | |
1069 / | |
1070 DAV / | |
1071 / | |
1072 v | |
1073 +---------+ | |
1074 | | | |
1075 | Apache | | |
1076 | | | |
1077 +---------+ | |
1078 | mod_DAV | | |
1079 +-------------+ | |
1080 | mod_DAV_SVN | | |
1081 +----------+-------------+--------------+----------+ <=== Filesystem interface
1082 | |
1083 | Subversion Filesystem |
1084 | |
1085 +--------------------------------------------------+
1087 </pre>
1094 <p>The Subversion client, which may be either
1095 command-line or GUI, draws on three libraries.</p>
1098 an API for managing the client's working copy of a project. This
1099 includes operations like renaming or removal of files, patching files,
1100 extracting local diffs, and routines for maintaining administrative
1104 provides an API for exchanging information with a Subversion
1105 repository. This includes the ability to read files, write new
1106 revisions of files, and ask the repository to compare a working copy
1107 against its latest revision. Note that there are two implementations
1108 of this interface: one designed to talk to a repository over a network,
1109 and one designed to work with a repository on local disk. Any number
1110 of interface implementations can exist.</p>
1116 theory, provide an API that allows anyone to write a Subversion client
1117 application.</p>
1126 <p> The network layer's job is to move the repository API requests
1127 over a wire.</p>
1129 <p>On the client side, a network library
1131 HTTP WebDAV/DeltaV requests. The information is sent over TCP/IP to an
1132 Apache server. Apache is used for the following reasons:</p>
1134 <ul>
1135 <li><p>it is time-tested and extremely
1136 stable;</p></li>
1138 <li><p>it has built-in proxy and firewall
1139 support;</p></li>
1140 <li><p>it has authentication and encryption
1141 features;</p></li>
1144 </ul>
1148 towards Apache's already-existing feature set. (However, Subversion's
1150 anyone from writing a totally new network access
1151 implementation.)</p>
1154 DAV requests into API calls against a particular repository.</p>
1156 <p>For details, see <a href="#protocol">Protocol — How the client and server communicate</a>.</p>
1163 <p>When the requests reach a particular repository, they are
1166 Filesystem is a custom Unix-like filesystem, with a twist: writes are
1167 revisioned and atomic, and no data is ever deleted! This filesystem is
1168 currently implemented on top of a normal filesystem, using Berkeley DB
1169 files.</p>
1171 <p>For a more detailed explanation: see <a href="#server">Server — How the server works</a>.</p>
1182 <ul>
1185 delta</strong></strong> describes the difference between two
1186 arbitrary directory trees, the way a traditional patch describes the
1187 difference between two files. For example, the delta between
1188 directories A and B could be applied to A, to produce B.</p>
1190 <p>Tree deltas can also carry ancestry information, indicating how
1191 the files in one tree are related to files in the other tree. And
1192 deltas can describe changes to file meta-information, like permission
1193 bits, creation dates, and so on. The repository and working copy use
1194 deltas to communicate changes.</p></li>
1197 delta</strong></strong> describes changes to a string of
1198 bytes, such as the contents of a file. It is analogous to
1199 traditional patch format, except that it works equally well on binary
1200 and text files, and is not invertible (because context and deleted
1201 data are not recorded).</p></li>
1204 delta</strong></strong> describes changes to a list of named
1206 </ul>
1209 means a tree delta, unless some other meaning is clear from
1210 context.</p>
1212 <p>In the examples below, deltas will be described in XML, which happens
1213 to be Subversion's (now mostly defunct) import/export patch format.
1214 However, note that deltas are an abstract data structure, of which the
1215 XML format is merely one representation. Later, we will describe other
1216 representations: for example, there is a serialized representation
1217 (useful for streaming protocols, among other things), and a db-style
1218 representation, used for repository storage. The various representations
1219 of a given delta are (in theory, anyway) perfectly isomorphic to one
1220 another, since they describe the same underlying structure.</p>
1227 <p>A text delta describes the difference between two strings of bytes,
1230 string, we can compute a text delta; given a source string and a delta,
1231 we can reconstruct the target string. However, note that deltas are not
1232 invertible: you cannot always reconstruct the source string given the
1233 target string and delta.</p>
1236 representation for text deltas; however, diffs are not ideal for internal
1237 use by a revision control system, for several reasons:</p>
1239 <ul>
1240 <li><p>Diffs are line-oriented, which makes them human-readable,
1241 but sometimes makes them perform poorly on binary
1242 files.</p></li>
1243 <li><p>Diffs represent a series of replacements, exchanging
1244 selected ranges ofthe old text with new text; again, this is easy for
1245 humans to read, butit is more expensive to compute and less compact
1246 than some alternatives.</p></li>
1247 </ul>
1249 <p>Instead, Subversion uses the VDelta binary-diffing algorithm, as
1251 empirical study of delta algorithms. Lecture Notes in Computer Science
1253 algorithm is stored in a custom data format called
1255 Subversion developer.</p>
1257 <p>The concrete form of a text delta is a well-formed XML element,
1258 having the following form:</p>
1260 <pre>
1262 </pre>
1265 encoded in the MIME Base64 format.</p>
1272 <p>A property delta describes changes to a property list, of the sort
1273 associated with files, directories, and directory entries, and revision
1275 creating, deleting, and changing the text of any number of
1276 properties.</p>
1278 <p>A property delta is an unordered set of name/change pairs. No two
1279 pairs within a given property delta have the same name. A pair's name
1280 indicates the property affected, and the change indicates what happens to
1281 its value. There are two kinds of changes:</p>
1283 <dl>
1285 <dd><p>Change the value of the named property to the byte
1287 with the given name, one is added to the property
1288 list.</p></dd>
1291 <dd><p>Remove the named property from the property
1292 list.</p></dd>
1294 </dl>
1297 or change a property value. However, this simplification means that the
1298 server cannot distinguish between a client which believes it is creating
1299 a value afresh, and a client which believes it is changing the value of
1300 an existing property. It may simplify conflict detection to divide
1305 which specifies a change to an existing property's value as a text delta.
1306 This would give us a compact way to describe small changes to large
1307 property values.</p>
1309 <p>The concrete form of a property delta is a well-formed XML element,
1310 having the following form:</p>
1312 <pre>
1314 </pre>
1317 the following forms:</p>
1319 <pre>
1320 <set name='<em class="replaceable">name</em>'><em class="replaceable">value</em></set>
1322 </pre>
1328 property.</p>
1330 <p>If either the property name or the property value contains the
1343 <p>A tree delta describes changes between two directory trees, the
1345 tree</strong>. Tree deltas can describe copies, renames, and
1346 deletions of files and directories, changes to file contents, and changes
1347 to property lists. A tree delta can also carry information about how the
1348 files in the target tree are derived from the files in the source tree,
1349 if this information is available.</p>
1351 <p>The format for tree deltas described here is easy to compute from a
1352 Subversion working directory, and easy to apply to a Subversion
1353 repository. Furthermore, the size of a tree delta in this format is
1354 independent of the commands used to produce the target tree — it
1355 depends only on the degree of difference between the source and target
1356 trees.</p>
1358 <p>A tree delta is interpreted in the context of three
1359 parameters:</p>
1361 <ul>
1363 directory to which this complete tree delta applies,</p></li>
1367 directory in the source tree that we are currently modifying to yield
1370 directory we're constructing.</p></li>
1371 </ul>
1373 <p>When we start interpreting a tree delta,
1379 corresponding portion of the source tree, which we use as the original.
1381 delta; we may use it to choose new source trees.</p>
1385 <pre>
1387 </pre>
1389 <p>which describe how to edit the contents of
1392 changes:</p>
1394 <dl>
1404 name='<em class="replaceable">name</em>'><em class="replaceable">content</em></add></dt>
1409 to which the new directory entry refers.</p></dd>
1413 name='<em class="replaceable">name</em>'><em class="replaceable">content</em></open></dt>
1418 or directory.</p></dd>
1420 </dl>
1423 aren't mentioned are assumed to appear unchanged in
1429 <p>In the change descriptions above, each
1431 forms:</p>
1433 <dl>
1443 </p>
1447 from that ancestor; it may be omitted, indicating that the
1448 properties are unchanged.</p>
1452 ancestor; it may also be omitted, indicating that
1454 ancestor's.</p></dd>
1462 — a fileelement with no property or text delta, thus
1463 describing a file identicalto its ancestor.</p></dd>
1475 any.</p>
1479 from that ancestor; it may be omitted, indicating thatthe
1480 properties are unchanged.</p>
1484 that ancestor; it may be omitted, indicating that the directory is
1486 should be interpreted with a new
1488 <tt class="filename"><em class="replaceable">target-dir</em>/<em class="replaceable">name</em></tt>.</p>
1491 complete tree delta structure, tree deltas are themselves trees,
1492 whose structure is a subgraph of the target tree.</p></dd>
1501 — a directory element with no property or tree delta, thus
1502 describing a directory identical to its ancestor.</p></dd>
1504 </dl>
1508 changes to the properties of that <em>directory
1513 one of the following forms:</p>
1515 <dl>
1519 <dd><p>The ancestor of the new or changed file or directory is
1520 <tt class="filename"><em class="replaceable">source-root</em>/<em class="replaceable">path</em></tt>,
1523 delta should be applied to
1524 <tt class="filename"><em class="replaceable">source-root</em>/<em class="replaceable">path</em></tt>.
1526 element,
1527 <tt class="filename"><em class="replaceable">source-root</em>/<em class="replaceable">path</em></tt>
1529 interpreting that element's tree delta.</p></dd>
1535 <dd><p>This indicates that the file or directory has no
1536 ancestor in the source tree. When followed by a
1538 to the empty file to yield the new text; when followed by a
1541 imaginary empty directory.</p></dd>
1549 for
1550 <tt class="literal">ancestor='<em class="replaceable">source-dir</em>/<em class="replaceable">name</em>'</tt>,
1551 with the same revision number. This makes the common case —
1552 files or directories modified in place — more
1553 compact.</p></dd>
1555 </dl>
1561 find the ancestor.</p>
1574 <pre>
1575 /dir1/file1
1576 file2
1577 dir2/file3
1578 file4
1579 dir3/file5
1580 file6
1581 </pre>
1584 describe the effect on the tree with the following tree delta, to be
1585 applied to the root:</p>
1587 <pre>
1599 </pre>
1602 made to the root directory. Within the root directory, there are changes
1613 <p>As another example, starting from the same source tree, suppose we
1617 <pre>
1630 </pre>
1637 directory. This is just an indirect way of describing the rename.</p>
1639 <p>Why is it necessary to be so indirect? Consider the delta
1640 representing the result of:</p>
1642 <ol>
1649 </ol>
1654 <pre>
1669 </pre>
1671 <p>The indirectness allows the tree delta to capture an arbitrary
1672 rearrangement without resorting to temporary filenames.</p>
1676 <ol>
1684 </ol>
1687 even though the directories around it have changed. Here is the tree
1688 delta:</p>
1690 <pre>
1716 </pre>
1720 <ul>
1727 and</p></li>
1732 </ul>
1734 <p>Some more possible maneuvers, left as exercises for the
1735 reader:</p>
1737 <ul>
1748 </ul>
1755 <p>It is sometimes useful to represent a set of changes to a tree
1756 without providing text deltas in the middle of the stream. Text deltas
1757 are often large and expensive to compute, and tree deltas can be useful
1758 without them. For example, one can detect whether two changes might
1760 without knowing exactly how the conflicting files changed.</p>
1762 <p>For this reason, our XML representation of a tree delta allows the
1764 closure. This allows the client to receive early notice of conflicts:
1766 tree-delta to the server, which can check for skeletal conflicts and
1767 reject the commit, before the client takes the time to transmit the
1768 (possibly large) textual changes. This potentially saves quite a bit of
1769 network traffic.</p>
1771 <p>In terms of XML, postfix text deltas are split into two parts. The
1772 first part appears "in-line" and contains a reference ID. The second
1773 part appears after the tree delta is complete. Here's an example:</p>
1775 <pre>
1790 </pre>
1798 <p>The static XML forms above are useful as an import/export format, and
1799 as a visualization aid, but we also need a way to express a delta as a
1801 diffing and patching. Subversion defines a standard set of such
1803 of function prototypes which anyone may implement (see
1808 distinct subtask of editing a directory tree. In fact, if you compare
1809 the editor function prototypes to the XML elements described previously,
1810 you'll notice a fairly strict correspondence: there's one function for
1811 replacing a directory, another function for replacing a file, one for
1812 adding a directory, another for adding a file, a function for deleting,
1813 and so on.</p>
1815 <p>Although the editor interface was designed around the general idea of
1816 making changes to a directory tree, a specific implementation's behavior
1817 depends on its role. For example, the versioning filesystem library
1818 offers an editor that creates new revisions, while the working copy
1819 library offers an editor that updates working copies. And the network
1820 layer offers an editor that turns editing calls into wire protocol, which
1821 is then converted back into editing calls on the other side! All of
1822 these different tasks can share a single interface, because they are all
1823 fundamentally about the same thing: expressing and applying differences
1824 between directory trees.</p>
1826 <p>Like the XML forms, a series of editor calls must follow certain
1827 nesting conventions; these conventions are implicit in the interface, in
1828 that some of the functions take arguments that can only be obtained from
1829 previous calls to other editor functions.</p>
1831 <p>Editors can best be understood by watching one work on a real
1832 directory tree. For example:</p>
1834 <!-- kff todo: fooo working here. -->
1836 <p>Suppose that the user has made a number of local changes to her
1837 working copy and wants to commit them to the repository. Let's represent
1838 her changes with the same tree-delta from a previous example. Notice
1839 that she has also made textual modifications to
1843 <pre>
1871 </pre>
1876 the network, as a series of individual commands given in depth-first
1877 order.</p>
1879 <p>Let's be more specific. The server presents the client with an
1882 really just table of functions; each function makes a change to a
1883 filesystem. Agent A (who has a private filesystem) presents an editor to
1884 agent B. Agent B then calls the editor's functions to change A's
1886 editor.</p>
1888 <p>As Karl Fogel likes to describe the process, if one thinks of the
1889 tree-delta as a lion, the editor is a "hoop" that the lion jumps through
1892 <p>B cannot call the functions in any willy-nilly order; there are some
1893 logical restrictions. In particular, as B drives the editor, it receives
1894 opaque data structures which represent directories and files. It must
1896 make further function calls.</p>
1898 <p>As an example, let's watch how the client would transmit the above
1899 tree-delta to the repository. (The description below is slightly
1900 simplified. For exact interface details, see
1903 <p>[Note: in the examples below, and throughout Subversion's code base,
1904 you'll see references to 'baton' objects. This is simply a project
1905 convention, a name given to structures that define contexts for
1906 functions. Many APIs call these structures 'userdata'. In Subversion,
1907 we like the term 'baton', because it reminds us of one function
1910 <ol>
1912 client.</p></li>
1917 of the repository's filesystem.</p></li>
1921 gives the client free license to make any changes it wants in the
1922 repository's root directory – until, of course, it calls
1925 return, the client now has a new opaque data structure that can be
1937 In particular, a new file is added to this directory whose ancestor
1940 <li><p>Now the text-delta associated with
1944 themselves, for network efficiency, are streamed in "chunks". So
1945 instead of receiving a baton object, we now have a routine that is
1946 able to receive any number of small "windows" of text-delta data.We
1948 functions right here; but suffice it to say that these routines are
1949 used for sending svndiff data to the
1953 client is done sending the file's text-delta, so it releases the file
1954 baton.</p></li>
1958 releases its baton as well.</p></li>
1960 <li><p>The client isn't yet finished with
1964 dir1_baton);</tt> <em>(The function's name is
1968 keyword.)</em></p></li>
1973 dir4_baton);</tt></p></li>
1975 <li><p>The client is now finished with both
1981 <li><p>The entire tree-delta is complete. The repository knows
1982 this when the root directory is closed:
1985 </ol>
1987 <p>Of course, at any point above, the repository may reject an edit. If
1988 this is the case, the client aborts the transmission and the repository
1989 hasn't changed a bit. (Thank goodness for transactions!)</p>
1992 direction as well. When the repository wishes to update a client's
1994 give a custom editor-object to the server, and the
1999 <ul>
2001 across the network, in both directions, using the same
2002 interface.</p></li>
2004 editor-implementations can be written to do anything one might want;
2005 the editor-driver has no idea what is happening on the other side of
2006 the interface. For example, an editor might
2007 </p><ul>
2008 <li><p>Output XML that matches the tree-delta DTD
2009 above;</p></li>
2010 <li><p>Output human-readable descriptions of the edits
2011 taking place;</p></li>
2013 </ul><p>
2014 </p></li>
2015 </ul>
2018 client and server do new and interesting things.</p>
2027 <p>The Subversion client is built on three libraries. One operates
2028 strictly on the working copy and does not talk to the repository.
2029 Another talks to the repository but never changes the working copy. The
2030 third library uses the first two to provide operations such as
2032 operations which need to both talk to the repository and change the
2033 working copy.</p>
2035 <p>The initial client is a Unix-style command-line tool (like standard
2036 CVS), but it should be easy to write a GUI client as well, based on the
2037 same libraries. The libraries capture the core Subversion functionality,
2038 segregating it from user interface concerns.</p>
2040 <p>This chapter describes the libraries, and the physical layout of
2041 working copies.</p>
2048 <p>Working copies are client-side directory trees containing both
2049 versioned data and Subversion administrative files. The functions in the
2050 working copy management library are the only functions in Subversion
2051 which operate on these trees.</p>
2057 <p>This section gives an overview of how
2058 working copies are arranged physically, but is not a full specification
2059 of working copy layout.</p>
2061 <p>As with CVS, Subversion working copies are simply directory trees
2062 with special administrative subdirectories, in this case named ".svn"
2065 <pre>
2066 myproj
2067 / | \
2068 _____________/ | \______________
2069 / | \
2070 .svn src doc
2071 ___/ | \___ /|\ ___/ \___
2072 | | | / | \ | |
2073 base ... ... / | \ myproj.texi .svn
2074 / | \ ___/ | \___
2075 ____/ | \____ | | |
2076 | | | base ... ...
2077 .svn foo.c bar.c |
2078 ___/ | \___ |
2079 | | | |
2080 base ... ... myproj.texi
2081 ___/ \___
2082 | |
2083 foo.c bar.c
2085 </pre>
2089 pristine revisions of all the files (for client-side delta generation),
2091 changes (such as uncommitted adds, deletes, and renames) that affect
2094 <p>Although it would often be possible to deduce certain information
2095 (such as the original repository) by examining parent directories, this
2096 is avoided in favor of making each directory be as much a
2097 self-contained unit as possible.</p>
2099 <p>For example, immediately after a checkout the administrative
2101 stored in one top-level file. But subdirectories instead keep track of
2102 their own revision information. This would be necessary anyway once
2103 the user starts committing new revisions for particular files, and it
2104 also makes it easier for the user to prune a big, complete tree into a
2105 small subtree and still have a valid working copy.</p>
2109 <ul>
2111 which version of the working copy adm format this is (so future
2112 clients can be backwards compatible easily).</p></li>
2115 containing the pristine repository revisions of the files in the
2116 corresponding working directory</p></li>
2119 revision numbers and other information for this directory and its
2120 files, and records the presence of subdirs. It also contains the
2121 repository URLs that each file and directory came from. It may
2122 help to think of this file as the functional equivalent of the
2126 property names and values for each file in the working
2127 directory.</p></li>
2130 containing pristine property names and values for each file in
2131 the working directory.</p></li>
2134 properties for this directory.</p></li>
2137 pristine properties for this directory.</p></li>
2140 implies that some client is currently operating on the
2141 administrative area.</p></li>
2144 scratch-work and helping make working copy operations more
2145 crash-proof.</p></li>
2148 indicates a list of actions that need to be taken to complete a
2149 working-copy-operation that is still "in
2151 </ul>
2153 <p>You can read much more about these files in the file
2161 <ul>
2163 </p><ul>
2165 </ul><p>
2166 </p></li>
2168 </p><ul>
2169 <li><p>ability to manipulate the working copy's versioned
2170 data</p></li>
2171 <li><p>ability to manipulate the working copy's
2172 administrative files</p></li>
2173 </ul><p>
2174 </p></li>
2175 </ul>
2181 evolving; please read the header file for a detailed description:
2190 <ul>
2192 </p><ul>
2193 <li><p>network access to a Subversion
2194 server</p></li>
2195 </ul><p>
2196 </p></li>
2198 </p><ul>
2199 <li><p>the ability to interact with a
2200 repository</p></li>
2201 </ul><p>
2202 </p></li>
2203 </ul>
2205 <p>This library performs operations involving communication with the
2206 repository.</p>
2208 <p>The interface defined in
2210 interface to both local and remote repository access.</p>
2213 this interface and speak to repositories using DAV requests. At some
2215 will provide the same interface – but will link directly to the
2216 filesystem library for accessing local disk repositories.</p>
2223 <ul>
2225 </p><ul>
2228 </ul><p>
2229 </p></li>
2231 </p><ul>
2233 </ul><p>
2234 </p></li>
2235 </ul>
2237 <p>These functions correspond to user-level client commands. In theory,
2238 any client interface (command-line, GUI, emacs, Python, etc.) should be
2240 ability to act as a full-featured Subversion client.</p>
2242 <p>Again, the detailed API can be found in
2252 <p>The wire protocol is the connection between the servers, and the
2255 in fact only a plugin manager, which delegates the actual task of
2256 communicating with a server to one of a selection of back-end modules (the
2258 one Subversion protocol - in fact, at present, there are two:</p>
2260 <ul>
2261 <li><p>The HTTP/WebDAV/DeltaV based protocol, implemented by the
2266 <li><p>The custom-designed protocol built directly upon TCP,
2269 </ul>
2282 Subversion filesystem calls.</p>
2286 <p>For a detailed description of exactly how Greg Stein
2288 Subversion, see his paper: <a href="http://svn.collab.net/repos/svn/trunk/www/webdav-usage.html">http://svn.collab.net/repos/svn/trunk/www/webdav-usage.html</a>
2289 </p>
2291 <p>For more information on WebDAV and the DeltaV extensions, see
2294 </p>
2306 over TCP. This protocol is documented at <a href="http://svn.collab.net/repos/svn/trunk/subversion/libsvn_ra_svn/protocol">http://svn.collab.net/repos/svn/trunk/subversion/libsvn_ra_svn/protocol</a>.</p>
2316 two different meanings: it can refer to a powerful computer which offers
2317 services to users on a network, or it can refer to a CPU process designed
2318 to receive network requests.</p>
2322 makes them available to other programs. No networking is
2323 required.</p>
2337 <ul>
2339 </p><ul>
2342 </ul><p>
2343 </p></li>
2345 </p><ul>
2349 [someday, not yet]</p></li>
2350 </ul><p>
2351 </p></li>
2352 </ul>
2353 <p>This library implements a hierarchical filesystem which supports
2354 atomic changes to directory trees, and records a complete history of
2355 the changes. In addition to recording changes to file and directory
2356 contents, the Subversion Filesystem records changes to file meta-data
2357 (see discussion of <strong class="firstterm">properties</strong> in <a href="#model">Model — The versioning model used by Subversion</a>).</p>
2364 <p> There are two main files that describe the Subversion
2365 filesystem.</p>
2368 for a general overview of how the filesystem works.</p>
2370 <p>Once you've done this, read Jim Blandy's own structural overview,
2371 which explains how nodes and revisions are organized (among other
2372 things) in the filesystem implementation:
2375 <p>Finally, read the well-documented API in
2387 <p>
2388 To begin, please be sure that you're already casually familiar with
2389 Subversion's ideas of files, directories, and revision histories. If
2390 not, see <a href="#model">Model — The versioning model used by Subversion</a>. We can now offer precise,
2391 technical descriptions of the terms introduced there.</p>
2393 <!-- This is taken from jimb's very first Subversion spec! -->
2395 <pre>
2397 canonically decomposed and ordered, according to the rules described in the
2398 Unicode standard.
2408 property list have the same name.
2413 directory below.) Nodes are distinguished unions — you can always tell
2414 whether a node is a file or a directory.
2433 and a property list.
2438 contiguous range of non-negative integers containing 0.
2442 </pre>
2444 <!-- Some definitions: we say that a node @var{n} is a @dfn{direct
2445 child} of a directory @var{d} iff @var{d} contains a directory entry
2446 whose node number is @var{n}. A node @var{n} is a @dfn{child} of a
2447 directory @var{d} iff @var{n} is a direct child of @var{d}, or if there
2448 exists some directory @var{e} which is a direct child of @var{d}, and
2449 @var{n} is a child of @var{e}. Given this definition of ``direct
2450 child'' and ``child,'' the obvious definitions of ``direct parent'' and
2451 ``parent'' hold.
2453 In these restrictions, let @var{r} be any repository. When we refer,
2454 implicitly or explicitly, to a node table without further
2455 clarification, we mean @var{r}'s node table. Thus, if we refer to ``a
2456 valid node number'' without specifying the node table in which it is
2457 valid, we mean ``a valid node number in @var{r}'s node table''.
2458 Similarly for @var{r}'s history. -->
2460 <p>Now that we've explained the form of the data, we make some
2461 restrictions on that form.</p>
2463 <p><strong>Every revision has a root
2464 directory.</strong> Every revision's node number is a valid node
2465 number, and the node it refers to is always a directory. We call
2469 directory.</strong> This baseline makes it easy to check out
2470 whole projects from the repository.</p>
2472 <p><strong>Directories contain only valid
2473 links.</strong> Every directory entry's
2476 <p><strong>Directory entries can be identified by
2479 name.</p>
2481 <p><strong>There are no cycles of
2484 <p><strong>Directories can have more than one
2485 parent.</strong> The Unix file system does not allow more than
2486 one hard link to a directory, but Subversion does allow the analogous
2487 situation. Thus, the directories in a Subversion repository form a
2489 However, it would be distracting and unhelpful to replace the
2495 node is a child of some revision's root directory.</p>
2497 <!-- </jimb> -->
2504 <p>This section provides a conversational explanation of how the
2505 repository actually stores and revisions file trees. It's not
2506 critical knowledge for a programmer using the Subversion Filesystem
2507 API, but most people probably still want to know what's going on
2511 (using CVS syntax):</p>
2513 <pre>
2514 prompt$ svn checkout myproj
2515 U myproj/
2516 U myproj/B
2517 U myproj/A
2518 U myproj/A/fish
2519 U myproj/A/fish/tuna
2520 prompt$
2521 </pre>
2524 everything else in myproj is a directory.</p>
2526 <p>Let's see what this looks like as an abstract data structure in
2527 the repository, and how that structure works in various operations
2528 (such as update, commit, and branch).</p>
2530 <p>In the diagrams that follow, lines represent parent-to-child
2531 connections in a directory hierarchy. Boxes are "nodes". A node is
2532 either a file or a directory – a letter in the upper left
2533 indicates which kind. A file node has a byte-string for its content,
2534 whereas directory nodes have a list of dir_entries, each pointing to
2535 another node.</p>
2537 <p>Parent-child links go both ways (i.e., a child knows who all its
2538 parents are), but a node's name is stored only in its parent, because
2539 a node with multiple parents may have different names in different
2540 parents.</p>
2542 <p>At the top of the repository is an array of revision numbers,
2543 stretching off to infinity. Since the project is at revision 1, only
2545 of the project:</p>
2547 <pre>
2548 ( myproj's revision array )
2549 ______________________________________________________
2550 |___1_______2________3________4________5_________6_____...
2551 |
2552 |
2553 ___|_____
2554 |D |
2555 | |
2556 | A | /* Two dir_entries, `A' and `B'. */
2557 | \ |
2558 | B \ |
2559 |__/___\__|
2560 / \
2561 | \
2562 | \
2563 ___|___ ___\____
2564 |D | |D |
2565 | | | |
2566 | | | fish | /* One dir_entry, `fish'. */
2567 |_______| |___\____|
2568 \
2569 \
2570 ___\____
2571 |D |
2572 | |
2573 | tuna | /* One dir_entry, `tuna'. */
2574 |___\____|
2575 \
2576 \
2577 ___\____
2578 |F |
2579 | |
2580 | | /* (Contents of tuna not shown.) */
2581 |________|
2583 </pre>
2587 latest text. The new node is not connected to anything yet, it's
2588 just hanging out there in space:</p>
2590 <pre>
2591 ________
2592 |F |
2593 | |
2594 | |
2595 |________|
2596 </pre>
2599 directory:</p>
2601 <pre>
2602 ________
2603 |D |
2604 | |
2605 | tuna |
2606 |___\____|
2607 \
2608 \
2609 ___\____
2610 |F |
2611 | |
2612 | |
2613 |________|
2614 </pre>
2616 <p>We continue up the line, creating a new revision of the next
2617 parent directory:</p>
2619 <pre>
2620 ________
2621 |D |
2622 | |
2623 | fish |
2624 |___\____|
2625 \
2626 \
2627 ___\____
2628 |D |
2629 | |
2630 | tuna |
2631 |___\____|
2632 \
2633 \
2634 ___\____
2635 |F |
2636 | |
2637 | |
2638 |________|
2639 </pre>
2641 <p>Now it gets more tricky: we need to create a new revision of the
2642 root directory. This new root directory needs an entry to point to
2644 all. Therefore, our new root directory also has an entry that still
2647 <pre>
2648 ______________________________________________________
2649 |___1_______2________3________4________5_________6_____...
2650 |
2651 |
2652 ___|_____ ________
2653 |D | |D |
2654 | | | |
2655 | A | | A |
2656 | \ | | \ |
2657 | B \ | | B \ |
2658 |__/___\__| |__/___\_|
2659 / \ / \
2660 | ___\_____________/ \
2661 | / \ \
2662 ___|__/ ___\____ ___\____
2663 |D | |D | |D |
2664 | | | | | |
2665 | | | fish | | fish |
2666 |_______| |___\____| |___\____|
2667 \ \
2668 \ \
2669 ___\____ ___\____
2670 |D | |D |
2671 | | | |
2672 | tuna | | tuna |
2673 |___\____| |___\____|
2674 \ \
2675 \ \
2676 ___\____ ___\____
2677 |F | |F |
2678 | | | |
2679 | | | |
2680 |________| |________|
2682 </pre>
2684 <p>Finally, after all our new nodes are written, we finish the
2686 available revision in the history array. In this case, the new tree
2689 <pre>
2690 ______________________________________________________
2691 |___1_______2________3________4________5_________6_____...
2692 | \
2693 | \__________
2694 ___|_____ __\_____
2695 |D | |D |
2696 | | | |
2697 | A | | A |
2698 | \ | | \ |
2699 | B \ | | B \ |
2700 |__/___\__| |__/___\_|
2701 / \ / \
2702 | ___\_____________/ \
2703 | / \ \
2704 ___|__/ ___\____ ___\____
2705 |D | |D | |D |
2706 | | | | | |
2707 | | | fish | | fish |
2708 |_______| |___\____| |___\____|
2709 \ \
2710 \ \
2711 ___\____ ___\____
2712 |D | |D |
2713 | | | |
2714 | tuna | | tuna |
2715 |___\____| |___\____|
2716 \ \
2717 \ \
2718 ___\____ ___\____
2719 |F | |F |
2720 | | | |
2721 | | | |
2722 |________| |________|
2724 </pre>
2726 <p>Generalizing on this example, you can now see that each
2728 node of a unique tree (and an atomic commit to the whole filesystem.)
2729 There are many trees in the repository, and many of them share
2730 nodes.</p>
2734 <ol>
2736 filesystem reader wants to locate revision
2738 it need only traverse the repository's history, locate revision
2742 <li><p><strong>Writers don't interfere with
2743 readers.</strong> Writers can continue to create new nodes,
2744 bubbling their way up to the top, and concurrent readers cannot
2745 see the work in progress. The new tree only becomes visible to
2747 the repository's history.</p></li>
2749 <li><p><strong>File structure is
2750 versioned.</strong> Unlike CVS, the very structure of each
2751 tree is being saved from revision to revision. File and
2752 directory renames, additions, and deletions are part of the
2753 repository's history.</p></li>
2754 </ol>
2756 <p>Let's demonstrate the last point by renaming the
2760 except that this parent directory has a different dir_entry, one
2762 different name:</p>
2764 <pre>
2765 ______________________________________________________
2766 |___1_______2________3________4________5_________6_____...
2767 | \
2768 | \__________
2769 ___|_____ __\_____
2770 |D | |D |
2771 | | | |
2772 | A | | A |
2773 | \ | | \ |
2774 | B \ | | B \ |
2775 |__/___\__| |__/___\_|
2776 / \ / \
2777 | ___\_____________/ \
2778 | / \ \
2779 ___|__/ ___\____ ___\____
2780 |D | |D | |D |
2781 | | | | | |
2782 | | | fish | | fish |
2783 |_______| |___\____| |___\____|
2784 \ \
2785 \ \
2786 ___\____ ___\____ ________
2787 |D | |D | |D |
2788 | | | | | |
2789 | tuna | | tuna | | book |
2790 |___\____| |___\____| |_/______|
2791 \ \ /
2792 \ \ /
2793 ___\____ ___\____ /
2794 |F | |F |
2795 | | | |
2796 | | | |
2797 |________| |________|
2798 </pre>
2800 <p>From here, we finish with the bubble-up process. We make new
2801 parent directories up to the top, culminating in a new root directory
2803 node we've had all along, the other to the new revision of
2807 <pre>
2808 ______________________________________________________
2809 |___1_______2________3________4________5_________6_____...
2810 | \ \_________________
2811 | \__________ \
2812 ___|_____ __\_____ __\_____
2813 |D | |D | |D |
2814 | | | | | |
2815 | A | | A | | A |
2816 | \ | | \ | | \ |
2817 | B \ | | B \ | | B \ |
2818 |__/___\__| |__/___\_| |__/___\_|
2819 / ___________________/_____\_________/ \
2820 | / ___\_____________/ \ \
2821 | / / \ \ \
2822 ___|/_/ ___\____ ___\____ _____\__
2823 |D | |D | |D | |D |
2824 | | | | | | | |
2825 | | | fish | | fish | | fish |
2826 |_______| |___\____| |___\____| |___\____|
2827 \ \ \
2828 \ \ \
2829 ___\____ ___\____ ___\____
2830 |D | |D | |D |
2831 | | | | | |
2832 | tuna | | tuna | | book |
2833 |___\____| |___\____| |_/______|
2834 \ \ /
2835 \ \ /
2836 ___\____ ___\____ /
2837 |F | |F |
2838 | | | |
2839 | | | |
2840 |________| |________|
2842 </pre>
2844 <p>For our last example, we'll demonstrate the way
2846 repository.</p>
2848 <p>In a nutshell, they're one and the same thing. Because nodes are
2850 directory entry that points to an existing directory node. It's an
2851 extremely cheap way of copying a tree; we call this new entry a
2855 <p>Let's go back to our original tree, assuming that we're at
2858 <pre>
2859 ______________________________________________________
2860 ...___6_______7________8________9________10_________11_____...
2861 |
2862 |
2863 ___|_____
2864 |D |
2865 | |
2866 | A |
2867 | \ |
2868 | B \ |
2869 |__/___\__|
2870 / \
2871 | \
2872 | \
2873 ___|___ ___\____
2874 |D | |D |
2875 | | | |
2876 | | | fish |
2877 |_______| |___\____|
2878 \
2879 \
2880 ___\____
2881 |D |
2882 | |
2883 | tuna |
2884 |___\____|
2885 \
2886 \
2887 ___\____
2888 |F |
2889 | |
2890 | |
2891 |________|
2893 </pre>
2897 root, pointing to A's node:</p>
2899 <pre>
2900 ______________________________________________________
2901 |___6_______7________8________9________10_________11_____...
2902 | \
2903 | \
2904 ___|_____ __\______
2905 |D | |D |
2906 | | | |
2907 | A | | A |
2908 | \ | | | |
2909 | B \ | | B | T |
2910 |__/___\__| |_/__|__|_|
2911 / \ / | |
2912 | ___\__/ / /
2913 | / \ / /
2914 ___|__/ ___\__/_ /
2915 |D | |D |
2916 | | | |
2917 | | | fish |
2918 |_______| |___\____|
2919 \
2920 \
2921 ___\____
2922 |D |
2923 | |
2924 | tuna |
2925 |___\____|
2926 \
2927 \
2928 ___\____
2929 |F |
2930 | |
2931 | |
2932 |________|
2934 </pre>
2936 <p>Now we're all set. In the future, the contents of directories A
2937 and B may change quite a lot. However, assuming we never make any
2939 a particular pristine revision of directory A at some point in time.
2940 Thus, T is a tag.</p>
2942 <p>(In theory, we can use some kind of authorization system to
2943 prevent anyone from writing to directory T. In practice, a well-laid
2945 in one place, so that it's clear to all users that they're not meant
2946 to change.)</p>
2949 directory T, and now our repository tree increments to revision 8,
2950 then T becomes a branch. Specifically, it's a branch of directory A
2951 which shares history with A up to a certain point, and then
2960 seems nice, but it sure wastes a lot of space. Every commit to the
2961 repository creates an entire line of new directory
2964 <p>Like many other revision control systems, Subversion stores
2965 changes as differences. It doesn't make complete copies of nodes;
2967 text, and previous revisions as a succession of reverse diffs (the
2969 for directories, it means a format that expresses changes to
2970 directories).</p>
2980 <ul>
2981 <li><p>The filesystem will be implemented as a library on
2982 Unix.</p></li>
2984 <li><p>The filesystem's data will probably be stored in a
2985 collection of .db files, using the Berkeley Database library.
2987 (In the future, of course, contributors are free
2988 modify the Subversion filesystem to operate with more powerful
2989 SQL database.)
2990 (For more information, see
2992 </ul>
3000 <!-- Jimb, Karl: Maybe we should turn this into a discussion about how the
3001 filesystem will use non-historical properties for internal ACLs, and how
3002 people can add "external" ACL systems via historical properties...? -->
3005 contains a number of components:</p>
3007 <ul>
3008 <li><p>a versioned filesystem (typically a collection of .db
3009 files)</p></li>
3010 <li><p>some hook scripts (for executing before or after
3011 commits)</p></li>
3012 <li><p>a locking area (used by Berkeley DB or other
3013 processes)</p></li>
3014 <li><p>a configuration area (for changing global
3015 behaviors)</p></li>
3016 </ul>
3018 <p>The Subversion filesystem is just that: a filesystem. But it's also
3019 useful to provide an API that acts at the level of the repository. The
3023 routines, such as those for beginning and ending commits, so that
3024 hook-scripts can run. A pre-commit-hook script might check for a valid
3025 log message, and a post-commit-hook script might send an email to a
3026 mailing list.</p>
3028 <p>Additionally, the repository library provides convenience routines
3029 for examining and manipulating the filesystem. For example, a routine to
3030 generate a tree-delta by comparing two revisions, routines for
3031 constructing new transactions, routines for querying log messages, and
3032 routines for exporting and importing filesystem data.</p>
3043 <p>This software is licensed as described in the file
3045 this distribution. The terms are also available at
3046 <a href="http://subversion.tigris.org/license-1.html">http://subversion.tigris.org/license-1.html</a>. If newer
3047 versions of this license are posted there, you may use a newer version
3048 instead, at your option.</p>
3053 </div>
3054 </body>
3055 </html>