← Back to branch summary

~bzr-pqm/bzr/bzr.dev

« back to all changes in this revision

Viewing changes to doc/developers/transports.txt

  • Committer: Martin Pool
  • Date: 2010-07-16 09:50:19 UTC
  • mto: This revision was merged to the branch mainline in revision 5348.
  • Revision ID: mbp@canonical.com-20100716095019-kjh4aqnh4oqqtq6s
Add some developer docs about symlinks and transports towards bug 192859

Show diffs side-by-side

added added

removed removed

Lines of Context:
doc/developers/transports.txt
 
1
####################################
 
2
Developer guide to bzrlib transports
 
3
####################################
 
4
 
 
5
This guide describes the `Transport` classes that Bazaar uses for most
 
6
local and remote file access.  (Working tree files are the major
 
7
exception.)
 
8
 
 
9
 
 
10
Handling symlinks
 
11
#################
 
12
 
 
13
A symlink creates an alias where files or directories can be accessed by a
 
14
different name.  Symlinks are annoying.
 
15
 
 
16
It's important to have tests for symlinks but there tests can't run on
 
17
Windows, so you need eg ::
 
18
 
 
19
    _test_needs_features = [tests.SymlinkFeature]
 
20
 
 
21
or ::
 
22
 
 
23
    self.requireFeature(tests.SymlinkFeature)
 
24
 
 
25
Bazaar versions symlinks as objects in their own right, whose content is
 
26
the (Unicode) path they point to.  bzr doesn't care whether a versioned
 
27
symlink is absolute or relative; or whether it points inside or outside
 
28
the working tree; or whether its referent exists or not.
 
29
 
 
30
So when we say ``bzr add symlink``, this should always add the symlink to
 
31
its containing working tree, and never dereference the symlink.
 
32
 
 
33
However, ``bzr add symlink/file`` shouldn't add ``file`` as a child of
 
34
``symlink``.  (Symlinks don't have files underneath them: they may point to
 
35
a directory which contains children, but if the symlink was pointed
 
36
somewhere else those children would be unaffected.)  This could either add
 
37
the file in its containing working tree, or fail outright.
 
38
 
 
39
One interesting case for this is ::
 
40
 
 
41
    bzr add ~/dev/bug123/a.c
 
42
 
 
43
where ``~/dev`` is actually a symlink to ``/srv/dev/joe/``.  In this case
 
44
clearly the user does want us to follow the symlink to open the tree.
 
45
 
 
46
As of bzr2.2, when we open a `WorkingTree`, we typically immediately
 
47
compute its real path and store that as ``.basedir``, but `BzrDir` stores
 
48
its apparent path.  (This may not be the best thing.)
 
49
 
 
50
 
 
51
Relative paths beyond symlinks
 
52
------------------------------
 
53
 
 
54
Another interesting case is when a control directory contains a relative
 
55
path, perhaps from a branch to its master or from a working tree to its
 
56
branch.  If it contains ``../`` parts as it typically will, these may have
 
57
different effects depending on whether they're looked up relative to the
 
58
real path or the apparent path given by the user.  It may be that some
 
59
users expect different behaviours at different times.  
 
60
 
 
61
Resolving the path relative to the real directory makes it somewhat more
 
62
consistent with what you would see by in a shell entering that directory
 
63
and then opening the given name.  It may also make things more consistent
 
64
when there are multiple links to the same bzrdir.  However it may cause
 
65
problems when using a transport that hides symlinks.
 
66
 
 
67
We could possibly handle this by doing less path arithmetic and asking the
 
68
OS or server to open the path including ``..`` and other relative
 
69
elements, but that might cause other problems.  HTTP servers may do their
 
70
own path arithmetic before passing it to the OS.
 
71
 
 
72
 
 
73
Transports that hide symlinks
 
74
-----------------------------
 
75
 
 
76
On local, sftp and bzr+ssh transports, we can directly see symlinks as
 
77
symlinks.  Over http (and ftp?) they're expanded by the server and we
 
78
cannot detect them.  This can cause problems when bzr follows relative
 
79
paths because typically we will join the paths, and we may do this
 
80
inconsistently with how the server, which can see the symlinks, would do.
 
81
 
 
82
 
 
83
Symlinks and ChrootTransports
 
84
-----------------------------
 
85
 
 
86
bzr has an internal concept of a `ChrootTransport` that locks access into
 
87
a particular directory.  Symlinks should not break out of a chroot jail
 
88
which implies they should be expanded and checked within bzrlib.
 
89
(At least as long as the transport lets us see the symlink; otherwise it
 
90
may not be possible.) 
 
91
 
 
92
 
 
93
 .. vim: ft=rst sw=4