NameDateSize

..20-Dec-201630

adm_crawler.cH A D08-Mar-201550.3 KiB

adm_files.cH A D08-Mar-201521.3 KiB

adm_files.hH A D08-Mar-20156.4 KiB

adm_ops.cH A D08-Mar-201550.6 KiB

ambient_depth_filter_editor.cH A D08-Mar-201521.7 KiB

cleanup.cH A D08-Mar-20158 KiB

conflicts.cH A D08-Mar-2015115.2 KiB

conflicts.hH A D08-Mar-201518.4 KiB

context.cH A D08-Mar-20153.4 KiB

copy.cH A D08-Mar-201541 KiB

crop.cH A D08-Mar-201514.3 KiB

delete.cH A D08-Mar-201519.2 KiB

deprecated.cH A D08-Mar-2015162.2 KiB

diff.hH A D08-Mar-20155.9 KiB

diff_editor.cH A D08-Mar-201599.2 KiB

diff_local.cH A D08-Mar-201519.6 KiB

entries.cH A D08-Mar-2015102.3 KiB

entries.hH A D08-Mar-20156.8 KiB

externals.cH A D08-Mar-201561 KiB

info.cH A D08-Mar-201522.1 KiB

lock.cH A D08-Mar-201552.3 KiB

lock.hH A D08-Mar-20153.1 KiB

merge.cH A D08-Mar-201557 KiB

node.cH A D08-Mar-201552.7 KiB

old-and-busted.cH A D08-Mar-201542.1 KiB

props.cH A D08-Mar-201584.8 KiB

props.hH A D08-Mar-20155.7 KiB

questions.cH A D08-Mar-201522.7 KiB

READMEH A D08-Mar-20158.9 KiB

relocate.cH A D08-Mar-20155.9 KiB

revert.cH A D08-Mar-201531.9 KiB

revision_status.cH A D08-Mar-20152.5 KiB

status.cH A D08-Mar-2015109.6 KiB

token-map.hH A D08-Mar-20152.5 KiB

translate.cH A D08-Mar-201515 KiB

translate.hH A D08-Mar-20157.9 KiB

tree_conflicts.cH A D08-Mar-201517.6 KiB

tree_conflicts.hH A D08-Mar-20153.3 KiB

update_editor.cH A D08-Mar-2015209.1 KiB

upgrade.cH A D08-Mar-201586 KiB

util.cH A D08-Mar-201521 KiB

wc-checks.hH A D08-Mar-20152.2 KiB

wc-checks.sqlH A D08-Mar-20153 KiB

wc-metadata.hH A D08-Mar-201518.7 KiB

wc-metadata.sqlH A D08-Mar-201534.4 KiB

wc-queries.hH A D08-Mar-2015110.5 KiB

wc-queries.sqlH A D08-Mar-201556.5 KiB

wc.hH A D08-Mar-201532.6 KiB

wc_db.cH A D08-Mar-2015531.1 KiB

wc_db.hH A D08-Mar-2015139.8 KiB

wc_db_pristine.cH A D08-Mar-201534 KiB

wc_db_private.hH A D08-Mar-201518.3 KiB

wc_db_update_move.cH A D08-Mar-2015103.5 KiB

wc_db_util.cH A D08-Mar-20157.5 KiB

wc_db_wcroot.cH A D08-Mar-201533.1 KiB

wcroot_anchor.cH A D08-Mar-20158 KiB

workqueue.cH A D08-Mar-201560.5 KiB

workqueue.hH A D08-Mar-20159.3 KiB

README

1     Oh Most High and Fragrant Emacs, please be in -*- text -*- mode!
2
3##############################################################################
4### The vast majority of this file is completely out-of-date as a result   ###
5### of the ongoing work known as WC-NG.  Please consult that documentation ###
6### for a more relevant and complete reference.                            ###
7### (See the files in notes/wc-ng )                                        ###
8##############################################################################
9
10
11This is the library described in the section "The working copy
12management library" of svn-design.texi.  It performs local operations
13in the working copy, tweaking administrative files and versioned data.
14It does not communicate directly with a repository; instead, other
15libraries that do talk to the repository call into this library to
16make queries and changes in the working copy.
17
18Note: This document attempts to describe (insofar as development is still
19a moving target) the current working copy layout.  For historic layouts,
20consulting the versioned history of this file (yay version control!)
21
22
23The Problem We're Solving
24-------------------------
25
26The working copy is arranged as a directory tree, which, at checkout,
27mirrors a tree rooted at some node in the repository.  Over time, the
28working copy accumulates uncommitted changes, some of which may affect
29its tree layout.  By commit time, the working copy's layout could be
30arbitrarily different from the repository tree on which it was based.
31
32Furthermore, updates/commits do not always involve the entire tree, so
33it is possible for the working copy to go a very long time without
34being a perfect mirror of some tree in the repository.
35
36
37One Way We're Not Solving It
38----------------------------
39
40Updates and commits are about merging two trees that share a common
41ancestor, but have diverged since that ancestor.  In real life, one of
42the trees comes from the working copy, the other from the repository.
43But when thinking about how to merge two such trees, we can ignore the
44question of which is the working copy and which is the repository,
45because the principles involved are symmetrical.
46
47Why do we say symmetrical?
48
49It's tempting to think of a change as being either "from" the working
50copy or "in" the repository.  But the true source of a change is some
51committer -- each change represents some developer's intention toward
52a file or a tree, and a conflict is what happens when two intentions
53are incompatible (or their compatibility cannot be automatically
54determined).
55
56It doesn't matter in what order the intentions were discovered --
57which has already made it into the repository versus which exists only
58in someone's working copy.  Incompatibility is incompatibility,
59independent of timing.
60
61In fact, a working copy can be viewed as a "branch" off the
62repository, and the changes committed in the repository *since* then
63represent another, divergent branch.  Thus, every update or commit is
64a general branch-merge problem:
65
66   - An update is an attempt to merge the repository's branch into the
67     working copy's branch, and the attempt may fail wholly or
68     partially depending on the number of conflicts.
69
70   - A commit is an attempt to merge the working copy's branch into
71     the repository.  The exact same algorithm is used as with
72     updates, the only difference being that a commit must succeed
73     completely or not at all.  That last condition is merely a
74     usability decision: the repository tree is shared by many
75     people, so folding both sides of a conflict into it to aid
76     resolution would actually make it less usable, not more.  On the
77     other hand, representing both sides of a conflict in a working
78     copy is often helpful to the person who owns that copy.
79
80So below we consider the general problem of how to merge two trees
81that have a common ancestor.  The concrete tree layout discussed will
82be that of the working copy, because this library needs to know
83exactly how to massage a working copy from one state to another.
84
85
86Structure of the Working Copy
87-----------------------------
88
89Working copy meta-information is stored in a single .svn/ subdirectory, in
90the root of a given working copy.  For the purposes of storage, directories
91pull in through the use of svn:externals are considered separate working
92copies.
93
94  .svn/wc.db                    /* SQLite database containing node metadata. */
95       pristine/                /* Sharded directory containing base files. */
96       tmp/                     /* Local tmp area. */
97
98`wc.db':
99   A self-contained SQLite database containing all the metadata Subversion
100   needs to track for this working copy.  The schema is described by
101   libsvn_wc/wc-metadata.sql.
102
103`pristine':
104   Each file in the working copy has a corresponding unmodified version in
105   the .svn/pristine subdirectory.  This files are stored by the SHA-1
106   hash of their contents, sharded into 256 subdirectories based upon the
107   first two characters of the hex expansion of the hash.  In this way,
108   multiple identical files can share the same pristine representation.
109
110   Pristines are used for sending diffs back to the server, etc.
111
112
113How the client applies an update delta
114--------------------------------------
115
116Updating is more than just bringing changes down from the repository;
117it's also folding those changes into the working copy.  Getting the
118right changes is the easy part -- folding them in is hard.
119
120Before we examine how Subversion handles this, let's look at what CVS
121does:
122
123   1. Unmodified portions of the working copy are simply brought
124      up-to-date.  The server sends a forward diff, the client applies
125      it.
126
127   2. Locally modified portions are "merged", where possible.  That
128      is, the changes from the repository are incorporated into the
129      local changes in an intelligent way (if the diff application
130      succeeds, then no conflict, else go to 3...)
131
132   3. Where merging is not possible, a conflict is flagged, and *both*
133      sides of the conflict are folded into the local file in such a
134      way that it's easy for the developer to figure out what
135      happened.  (And the old locally-modified file is saved under a
136      temp name, just in case.)
137
138It would be nice for Subversion to do things this way too;
139unfortunately, that's not possible in every case.
140
141CVS has a wonderfully simplifying limitation: it doesn't version
142directories, so never has tree-structure conflicts.  Given that only
143textual conflicts are possible, there is usually a natural way to
144express both sides of a conflict -- just include the opposing texts
145inside the file, delimited with conflict markers.  (Or for binary
146files, make both revisions available under temporary names.)
147
148While Subversion can behave the same way for textual conflicts, the
149situation is more complex for trees.  There is sometimes no way for a
150working copy to reflect both sides of a tree conflict without being
151more confusing than helpful.  How does one put "conflict markers" into
152a directory, especially when what was a directory might now be a file,
153or vice-versa?
154
155Therefore, while Subversion does everything it can to fold conflicts
156intelligently (doing at least as well as CVS does), in extreme cases
157it is acceptable for the Subversion client to punt, saying in effect
158"Your working copy is too out of whack; please move it aside, check
159out a fresh one, redo your changes in the fresh copy, and commit from
160that."  (This response may also apply to subtrees of the working copy,
161of course).
162
163Usually it offers more detail than that, too.  In addition to the
164overall out-of-whackness message, it can say "Directory foo was
165renamed to bar, conflicting with your new file bar; file blah was
166deleted, conflicting with your local change to file blah, ..." and so
167on.  The important thing is that these are informational only -- they
168tell the user what's wrong, but they don't try to fix it
169automatically.
170
171All this is purely a matter of *client-side* intelligence.  Nothing in
172the repository logic or protocol affects the client's ability to fold
173conflicts.  So as we get smarter, and/or as there is demand for more
174informative conflicting updates, the client's behavior can improve and
175punting can become a rare event.  We should start out with a _simple_
176conflict-folding algorithm initially, though.
177
178
179Text and Property Components
180----------------------------
181
182A Subversion working copy keeps track of *two* forks per file, much
183like the way MacOS files have "data" forks and "resource" forks.  Each
184file under revision control has its "text" and "properties" tracked
185with different timestamps and different conflict (reject) files.  In
186this vein, each file's status-line has two columns which describe the
187file's state.
188
189Examples:
190
191  --  glub.c      --> glub.c is completely up-to-date.
192  U-  foo.c       --> foo.c's textual component was updated.
193  -M  bar.c       --> bar.c's properties have been locally modified
194  UC  baz.c       --> baz.c has had both components patched, but a
195                      local property change is creating a conflict.
196