← 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 merge tweaks from aaron, which includes latest .dev

Show diffs side-by-side

added added

removed removed

Lines of Context:
doc/developers/colocated-branches.txt
1
 
co-located branches
2
 
===================
3
 
 
4
 
At the moment, each Bazaar branch has a separate directory in the file
5
 
system. While this works well, and makes it very easy to discover
6
 
branches there are several situations where it might be useful to also
7
 
support multiple branches under the same file system directory.
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
 
 
14
 
Rationale
15
 
---------
16
 
 
17
 
Allowing multiple branches to live under the same directory in the file
18
 
system means that it is possible to very easily share the same working
19
 
tree and repository between those branches, without having a lot of fs
20
 
infrastructure. 
21
 
 
22
 
Git and Mercurial (can) store multiple branches under a single directory
23
 
in the file system - per repository, so to speak. In order for this to
24
 
be accessible in Bazaar, Bazaar needs to have the right APIs and UI for
25
 
accessing these branches.
26
 
 
27
 
Use Cases
28
 
---------
29
 
 
30
 
Carla has a large C-based project with a large tree and a lot of .o
31
 
files that get generated as part of her build process. She doesn't want
32
 
to create a new working tree for each new branch but simply uses "bzr
33
 
switch" to switch between the different colocated branches that all use
34
 
the same working tree.
35
 
 
36
 
Brad has a single project with a lot of related branches. He works on
37
 
them and occasionally pushes all of those branches to a remote host
38
 
using a single push command.
39
 
 
40
 
Joe follows one of his co-workers local branches in Mercurial by pulling
41
 
into Bazaar.
42
 
 
43
 
Implementation
44
 
--------------
45
 
 
46
 
UI Changes
47
 
~~~~~~~~~~
48
 
 
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
56
 
 
57
 
Code Changes
58
 
~~~~~~~~~~~~
59
 
 
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.
100
 
 
101
 
Schema Changes
102
 
--------------
103
 
 
104
 
No format changes are necessary at first; at least, even if Bazaar
105
 
provides the right infrastructure it doesn't have to support this
106
 
feature in its own file formats.
107
 
 
108
 
Eventually, Bazaar could easily support colocated branches by just
109
 
creating a new branch transport for each colocated branch and have a 
110
 
"regular" branch live there. This would require something like
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