← Back to branch summary

~bzr-pqm/bzr/bzr.dev

« back to all changes in this revision

Viewing changes to doc/developers/colocated-branches.txt

Merge bzr.dev into cleanup

Show diffs side-by-side

added added

removed removed

Lines of Context:
doc/developers/colocated-branches.txt
6
6
branches there are several situations where it might be useful to also
7
7
support multiple branches under the same file system directory.
8
8
 
 
9
There is an experimental implementation for Bazaar available as a plugin
 
10
at http://people.samba.org/bzr/jelmer/bzr-local-branches/trunk. This was
 
11
the original proof-of-concept and doesn't yet use the API documented
 
12
here.
 
13
 
9
14
Rationale
10
15
---------
11
16
 
41
46
UI Changes
42
47
~~~~~~~~~~
43
48
 
44
 
Bazaar URLs need to have some way to address colocated branches in 
45
 
directories that contain multiple branches. 
46
 
 
47
 
Per RFC3986 we have picked the comma (",") to allow the specification of 
48
 
colocated branch names. Comma's in path names would have to be 
49
 
urlencoded at first to avoid ambiguity, though perhaps it would be 
50
 
possible to support heuristics later when interpreting user-specified URLs.
51
 
 
52
 
An example URL would be:
53
 
 
54
 
 bzr://bazaar.launchpad.net/~jelmer/bzr/bzr.dev,colo-urls
55
 
 
56
 
The segment after the comma will initially be interpreted as a colocated 
57
 
branch name but we would like to keep the option to allow 
58
 
key=value style specifications in the future and DWIM for segments that 
59
 
do not contain an =. Following the RFC the comma would be interpreted within
60
 
the scope of a path segment. In other words, in the URL:
61
 
 
62
 
 git://git.debian.org/pkg-python-debian/python-debian.git,unstable/README
63
 
 
64
 
unstable is interpreted as the colocated branch living in the python-debian.git
65
 
control directory; README is a path inside of the branch.
66
 
 
67
 
Control directories will also have the notion of an "active" branch. This is 
68
 
the branch that is being used by a working tree, if present and the branch 
69
 
that will be used if no explicit colocated branch is specified. The 
70
 
active branch support makes it easier to deal with existing bzrdirs and 
71
 
is useful when accessing foreign control directories that have the concept 
72
 
as well.
73
 
 
74
 
A new command 'bzr rmbranch' needs to be added to make it possible to 
75
 
remove colocated branches, as this won't be possible by simple 
76
 
directory removal, at least not of a user-visible directory.
 
49
Bazaar URLs need to have some way to specify a colocated branch other
 
50
than the current HEAD. Several options have been discussed, each with
 
51
its own advantages and disadvantages: This was discussed on the mailing
 
52
list, most notably the use of a ";branch=NAME" suffix as well as a special
 
53
separation character (+, =, etc), but no final conclusion was reached.
 
54
 
 
55
https://lists.ubuntu.com/archives/bazaar/2008q4/050105.html
77
56
 
78
57
Code Changes
79
58
~~~~~~~~~~~~
80
59
 
81
 
BzrDirFormat will need a supports_colocated_branches property that 
82
 
indicates whether a format supports the creation, removal and accessing of 
83
 
colocated branches.
84
 
 
85
 
Several methods on BzrDir will need to be updated to take an option branch_name 
86
 
parameter. If this parameter is not specified or None, the active branch 
87
 
will be used.
88
 
 
89
 
The methods that will have to be extended are:
90
 
 
91
 
 * BzrDir.open_branch()
92
 
 * BzrDir.create_branch()
93
 
 * BzrDir.destroy_branch()
94
 
 * BzrDir.get_branch_transport()
95
 
 
96
 
 * BranchFormat.initialise()
97
 
 * BranchFormat.open()
98
 
 
99
 
A new BzrDir.list_branches() method will return all colocated branches 
100
 
present in a control directory. 
101
 
 
102
 
Any URL interpreting methods (e.g. Branch.open) will need to be updated 
103
 
to extract a colocated branch name and need to pass that into the 
104
 
relevant methods.
105
 
 
106
 
Existing callers of BzrDir.{create,open,destroy}_branch() need to 
107
 
be updated to pass in branch names and optionally be changed to use 
108
 
BzrDir.list_branches().
 
60
BzrDir should support a BzrDir.supports_colocated_branches() call as well as
 
61
BzrDir.colocated_branches property that contains a colocated branch container,
 
62
that can be used to add / remove colocated branches as well as change the
 
63
currently active colocated branch.
 
64
 
 
65
::
 
66
 
 
67
        class ColocatedBranchContainer(object):
 
68
 
 
69
           def get_active_branch_name(self):
 
70
                  """Returns the name of the currently active branch.
 
71
 
 
72
                  This can be None if no branch is currently active.
 
73
                  """
 
74
 
 
75
           def get_active_branch(self):
 
76
                  """Returns the currently active branches' Branch object."""
 
77
 
 
78
           def get_branch(self, name):
 
79
                  """Returns the Branch object for the specified branch."""
 
80
 
 
81
           def available_branches(self):
 
82
                  """Returns a set with the names of the available branches."""
 
83
 
 
84
           def set_active_branch(self, name):
 
85
                  """Set the currently active branch."""
 
86
 
 
87
           def destroy_branch(self, name):
 
88
                 """Destroy the specified branch.
 
89
                        
 
90
                This will remove the branch from disk."""
 
91
 
 
92
If the particular BzrDir implementation doesn't support colocated
 
93
branches, it can just return a dummy container that just contains a
 
94
HEAD branch.
 
95
 
 
96
Looms can of course return a container with all their threads.
 
97
 
 
98
BzrDir.find_branches() should take into account the colocated branches
 
99
when iterating over its branches.
109
100
 
110
101
Schema Changes
111
102
--------------
117
108
Eventually, Bazaar could easily support colocated branches by just
118
109
creating a new branch transport for each colocated branch and have a
119
110
"regular" branch live there. This would require something like
120
 
BzrDirMeta2 though. An example of this is implemented in the 
121
 
lp:bzr-colocated plugin
122
 
 
123
 
Further integration
124
 
-------------------
125
 
 
126
 
Loggerhead and Launchpad need to be updated to show colocated branches
127
 
(perhaps in a similar way as they would show tags?).
128
 
 
129
 
qbzr/bzr-gtk need to be updated to support colocated branches.
 
111
BzrDirMeta2 though.
 
112
 
 
113
Unresolved Issues
 
114
-----------------
 
115
 
 
116
 * What about colocated looms ?
 
117
 * What character to use to name colocated branches in URLs?
 
118