/breezy/unstable

To get this branch, use:
bzr branch https://code.breezy-vcs.org/breezy/unstable

« back to all changes in this revision

Viewing changes to doc/en/user-guide/shared_repository_layouts.txt

  • Committer: Jelmer Vernooij
  • Date: 2017-05-24 01:39:33 UTC
  • mfrom: (3815.3776.6)
  • Revision ID: jelmer@jelmer.uk-20170524013933-ir4y4tqtrsiz2ka2
New upstream snapshot.

Show diffs side-by-side

added added

removed removed

Lines of Context:
1
1
Advanced shared repository layouts
2
2
==================================
3
3
 
4
 
Bazaar is designed to give you flexibility in how you layout branches inside a shared repository.
5
 
This flexibility allows users to tailor Bazaar to their workflow,
 
4
Breezy is designed to give you flexibility in how you layout branches inside a shared repository.
 
5
This flexibility allows users to tailor Breezy to their workflow,
6
6
but it also leads to questions about what is a "good" layout.
7
7
We present some alternatives and give some discussion about the benefits of each.
8
8
 
27
27
       +- release-X # A branch specific to mark a given release version
28
28
          ...
29
29
 
30
 
With Bazaar, that is a perfectly reasonable layout.
 
30
With Breezy, that is a perfectly reasonable layout.
31
31
It has the benefit of being familiar to people coming from SVN,
32
32
and making it clear where the development focus is.
33
33
 
52
52
       +- branches/      # Container for project2 branches
53
53
 
54
54
 
55
 
This also works with Bazaar.
56
 
However, with Bazaar repositories are cheap to create
57
 
(a simple ``bzr init-repo`` away), and their primary benefit is when the
 
55
This also works with Breezy.
 
56
However, with Breezy repositories are cheap to create
 
57
(a simple ``brz init-repo`` away), and their primary benefit is when the
58
58
branches share a common ancestry.
59
59
 
60
 
So the preferred way for Bazaar would be::
 
60
So the preferred way for Breezy would be::
61
61
 
62
62
    project1/          # A repository for project1
63
63
     +- trunk/         # The mainline of development of project1
103
103
I believe the reason for this in SVN, is so that someone
104
104
can checkout all of "``trunk/``" and get the all the mainlines for all projects.
105
105
 
106
 
This layout can be used for Bazaar, but it is not generally recommended.
 
106
This layout can be used for Breezy, but it is not generally recommended.
107
107
 
108
 
 1) ``bzr branch/checkout/get`` is a single branch at a time.
 
108
 1) ``brz branch/checkout/get`` is a single branch at a time.
109
109
    So you don't get the benefit of getting all mainlines with a single command. [1]_
110
110
 
111
111
 2) It is less obvious of whether ``repository/trunk/foo`` is the ``trunk`` of project
112
112
    ``foo`` or it is just the ``foo`` directory in the ``trunk`` branch.
113
113
    Some of this confusion is due to SVN, because it uses the same "namespace"
114
114
    for files in a project that it uses for branches of a project.
115
 
    In Bazaar, there is a clear distinction of what files make up a project, versus
116
 
    the location of the Branch. (After all, there is only one ``.bzr/`` directory per branch,
 
115
    In Breezy, there is a clear distinction of what files make up a project, versus
 
116
    the location of the Branch. (After all, there is only one ``.brz/`` directory per branch,
117
117
    versus many ``.svn/`` directories in the checkout).
118
118
 
119
119
.. [1] Note: `NestedTreeSupport`_ can provide a way to create "meta-projects" which
120
120
    aggregate multiple projects regardless of the repository layout.
121
 
    Letting you ``bzr checkout`` one project, and have it grab all the necessary
 
121
    Letting you ``brz checkout`` one project, and have it grab all the necessary
122
122
    sub-projects.
123
123
 
124
124
.. _NestedTreeSupport: http://wiki.bazaar.canonical.com/NestedTrees
127
127
Nested Style (``project/branch/sub-branch/``)
128
128
---------------------------------------------
129
129
 
130
 
Another style with Bazaar, which is not generally possible in SVN
 
130
Another style with Breezy, which is not generally possible in SVN
131
131
is to have branches nested within each-other.
132
 
This is possible because Bazaar supports (and recommends) creating repositories
 
132
This is possible because Breezy supports (and recommends) creating repositories
133
133
with no working trees (``--no-trees``).
134
134
With a ``--no-trees`` repository, because the working files are not intermixed with
135
135
your branch locations, you are free to put a branch in whatever namespace you want.
159
159
 
160
160
For example compare::
161
161
 
162
 
  bzr branch http://host/repository/project/branches/joe-feature-foo-bugfix-10/
 
162
  brz branch http://host/repository/project/branches/joe-feature-foo-bugfix-10/
163
163
 
164
164
Versus::
165
165
 
166
 
  bzr branch http://host/project/joe/foo/bugfix-10
 
166
  brz branch http://host/project/joe/foo/bugfix-10
167
167
 
168
168
 
169
169
Also, if you list the ``repository/project/branches/`` directory you might see something like::
188
188
 
189
189
One other small advantage is that you can do something like::
190
190
 
191
 
   bzr branch http://host/project/release/1/1/1
 
191
   brz branch http://host/project/release/1/1/1
192
192
  or
193
 
   bzr branch http://host/project/release/1/1/2
 
193
   brz branch http://host/project/release/1/1/2
194
194
 
195
195
To indicate release 1.1.1 and 1.1.2. This again depends on how many releases you have
196
196
and whether the gain of splitting things up outweighs the ability to see more at a glance.
222
222
 
223
223
The biggest disadvantage with this layout, is that branches move around.
224
224
Which means that if someone is following the ``project/dev/new-feature`` branch,
225
 
when it gets merged into ``trunk/`` suddenly ``bzr pull`` doesn't mirror the branch
 
225
when it gets merged into ``trunk/`` suddenly ``brz pull`` doesn't mirror the branch
226
226
for them anymore because the branch is now at ``project/merged/new-feature``.
227
227
There are a couple ways around this. One is to use HTTP redirects to point people
228
 
requesting the old branch to the new branch. ``bzr`` >= 0.15 will let users know
 
228
requesting the old branch to the new branch. ``brz`` >= 0.15 will let users know
229
229
that ``http://old/path redirects to http://new/path``. However, this doesn't help
230
230
if people are accessing a branch through methods other than HTTP (SFTP, local filesystem, etc).
231
231
 
233
233
is within the repository it should cause little trouble). However eventually you want to
234
234
remove the symlink, or you don't get the clutter reduction benefit.
235
235
Another possibility instead of a symlink is to use a ``BranchReference``. It is currently
236
 
difficult to create these through the ``bzr`` command line, but if people find them useful
 
236
difficult to create these through the ``brz`` command line, but if people find them useful
237
237
that could be changed.
238
 
This is actually how `Launchpad`_ allows you to ``bzr checkout https://launchpad.net/bzr``.
 
238
This is actually how `Launchpad`_ allows you to ``brz checkout https://launchpad.net/bzr``.
239
239
Effectively a ``BranchReference`` is a symlink, but it allows you to reference any other URL.
240
240
If it is extended to support relative references, it would even work over HTTP, SFTP,
241
241
and local paths.