← Back to branch summary

~bzr-pqm/bzr/bzr.dev

« back to all changes in this revision

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

  • Committer: Jelmer Vernooij
  • Date: 2009-02-09 18:35:47 UTC
  • mto: This revision was merged to the branch mainline in revision 3995.
  • Revision ID: jelmer@samba.org-20090209183547-rkky1894rwhkl7gn
Add specification for colocated-branches.

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 his 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 
 
34
colocated branches that all use 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
=== UI Changes  ===
 
46
 
 
47
Bazaar URLs need to have some way to specify a colocated branch other
 
48
than the current HEAD. Several options have been, each with its own
 
49
advantages and disadvantages: This was discussed on the mailing list,
 
50
most notably the use of a ";branch=NAME" suffix as well as a special
 
51
separation character (+, =, etc), but no final conclusion was reached. 
 
52
 
 
53
https://lists.ubuntu.com/archives/bazaar/2008q4/050105.html
 
54
 
 
55
=== Code Changes ===
 
56
 
 
57
BzrDir should support a BzrDir.get_colocated_branches() call returning a
 
58
colocated branch container, that can be used to add / remove colocated
 
59
branches as well as change the currently active colocated branch.
 
60
 
 
61
::
 
62
 
 
63
        class ColocatedBranchContainer(object):
 
64
 
 
65
           def get_active_branch_name(self):
 
66
                  """Returns the name of the currently active branch.
 
67
 
 
68
                  This can be None if no branch is currently active.
 
69
                  """
 
70
 
 
71
           def get_active_branch(self):
 
72
                  """Returns the currently active branches' Branch object."""
 
73
 
 
74
           def get_branch(self, name):
 
75
                  """Returns the Branch object for the specifie branch."""
 
76
 
 
77
           def available_branches(self):
 
78
                  """Returns a set with the names of the available branches."""
 
79
 
 
80
           def set_active_branch(self, name):
 
81
                  """Set the currently active branch."""
 
82
 
 
83
           def destroy_branch(self, name):
 
84
                 """Destroy the specified branch.""" 
 
85
 
 
86
If the particular BzrDir implementation doesn't support colocated
 
87
branches, it can just return a dummy container that just contains a HEAD
 
88
branch. 
 
89
 
 
90
Looms can of course return a container with all their threads.
 
91
 
 
92
BzrDir.find_branches() should take into account the colocated branches
 
93
when iterating over its branches.
 
94
 
 
95
Schema Changes
 
96
--------------
 
97
 
 
98
No format changes are necessary at first; at least, even if Bazaar
 
99
provides the right infrastructure it doesn't have to support this
 
100
feature in its own file formats.
 
101
 
 
102
Eventually, Bazaar could easily support colocated branches by just
 
103
creating a new branch transport for each colocated branch and have a 
 
104
"regular" branch live there. This would require something like
 
105
BzrDirMeta2 though.
 
106
 
 
107
Unresolved Issues
 
108
-----------------
 
109
 
 
110
 * What about colocated looms ?
 
111
 * What character to use to name colocated branches in URLs?
 
112