← Back to branch summary

~bzr-pqm/bzr/bzr.dev

« back to all changes in this revision

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

- add short-form of testaments

Show diffs side-by-side

added added

removed removed

Lines of Context:
doc/en/user-guide/svn_plugin.txt
1
 
bzr-svn
2
 
=======
3
 
 
4
 
Overview
5
 
--------
6
 
 
7
 
bzr-svn lets developers use Bazaar as their VCS client on projects
8
 
still using a central Subversion repository. Access to Subversion
9
 
repositories is largely transparent, i.e. you can use most ``bzr``
10
 
commands directly on Subversion repositories exactly the same
11
 
as if you were using ``bzr`` on native Bazaar branches.
12
 
 
13
 
Many bzr-svn users create a local mirror of the central Subversion
14
 
trunk, work in local feature branches, and submit their
15
 
overall change back to Subversion when it is ready
16
 
to go. This lets them gain many of the advantages of distributed
17
 
VCS tools without interrupting existing team-wide processes and
18
 
tool integration hooks currently built on top of Subversion. Indeed,
19
 
this is a common interim step for teams looking to adopt Bazaar but
20
 
who are unable to do so yet for timing or non-technical reasons.
21
 
 
22
 
For installation instructions, see the bzr-svn home page:
23
 
http://bazaar-vcs.org/BzrForeignBranches/Subversion.
24
 
 
25
 
 
26
 
A simple example
27
 
----------------
28
 
 
29
 
Here's a simple example of how you can use bzr-svn to hack on a
30
 
GNOME project like **beagle**. Firstly, setup a local shared repository
31
 
for storing your branches in and checkout the trunk::
32
 
 
33
 
  bzr init-repo --rich-root-pack beagle-repo
34
 
  cd beagle-repo
35
 
  bzr checkout svn+ssh://svn.gnome.org/svn/beagle/trunk beagle-trunk
36
 
 
37
 
Note that using the ``rich-root-pack`` option to ``init-repo`` is
38
 
important as bzr-svn requires some extra metadata not yet supported in Bazaar's
39
 
default repository format. Next, create a feature branch and hack away::
40
 
 
41
 
  bzr branch beagle-trunk beagle-feature1
42
 
  cd beagle-feature1
43
 
  *changes*
44
 
  bzr commit -m "blah blah blah"
45
 
  *changes*
46
 
  bzr commit -m "blah blah blah"
47
 
 
48
 
When the feature is cooked, refresh your trunk mirror and merge
49
 
your change::
50
 
 
51
 
  cd ../beagle-trunk
52
 
  bzr update
53
 
  bzr merge ../beagle-feature1
54
 
  bzr commit -m "Complete comment for SVN commit"
55
 
 
56
 
As your trunk mirror is a checkout, committing to it implicitly
57
 
commits to the real Subversion trunk. That's it!
58
 
 
59
 
 
60
 
Using a central repository mirror
61
 
---------------------------------
62
 
 
63
 
For large projects, it often makes sense to tweak the recipe given above.
64
 
In particular, the initial checkout can get quite slow so you may wish
65
 
to import the Subversion repository into a Bazaar one once and for all
66
 
for your project, and then branch from that native Bazaar repository
67
 
instead. bzr-svn provides the ``svn-import`` command for doing this
68
 
repository-to-repository conversion. Here's an example of how to use it::
69
 
 
70
 
  bzr init-repo --rich-root-pack beagle.bzr
71
 
  cd beagle.bzr
72
 
  bzr svn-import svn+ssh://svn.gnome.org/svn/beagle
73
 
 
74
 
Here's the recipe from above updated to use a central Bazaar mirror::
75
 
 
76
 
  bzr init-repo --rich-root-pack beagle-repo
77
 
  cd beagle-repo
78
 
  bzr branch bzr+ssh://bzr.gnome.org/beagle.bzr/trunk beagle-trunk
79
 
  bzr branch beagle-trunk beagle-feature1
80
 
  cd beagle-feature1
81
 
  *changes*
82
 
  bzr commit -m "blah blah blah"
83
 
  *changes*
84
 
  bzr commit -m "blah blah blah"
85
 
  cd ../beagle-trunk
86
 
  bzr pull
87
 
  bzr merge ../beagle-feature1
88
 
  bzr commit -m "Complete comment for SVN commit"
89
 
  bzr push
90
 
 
91
 
In this case, committing to the trunk only commits the merge locally.
92
 
To commit back to the master Subversion trunk, an additional command
93
 
(``bzr push``) is required.
94
 
 
95
 
Note: You'll need to give ``pull`` and ``push`` the relevant URLs
96
 
the first time you use those commands in the trunk branch. After that,
97
 
bzr remembers them.
98
 
 
99
 
The final piece of the puzzle in this setup is to put scripts in
100
 
place to keep the central Bazaar mirror synchronized with the Subversion
101
 
one. This can be done by adding a cron job, using a Subversion hook,
102
 
or whatever makes sense in your environment.
103
 
 
104
 
 
105
 
Limitations of bzr-svn
106
 
----------------------
107
 
 
108
 
Bazaar and Subversion are different tools with different capabilities
109
 
so there will always be some limited interoperability issues.
110
 
Here are some examples current as of bzr-svn 0.4.10:
111
 
 
112
 
 * Bazaar doesn't support versioned properties
113
 
 
114
 
 * Bazaar doesn't support tracking of file copies.
115
 
 
116
 
 * ``bzr push`` to an existing Subversion branch works but 
117
 
   ``bzr push`` to a new Subversion branch doesn't. Until
118
 
   the relevant bug is fixed (#121875), you need to use
119
 
   ``bzr svn-push`` in the latter case.
120
 
 
121
 
See the bzr-svn web page,
122
 
http://bazaar-vcs.org/BzrForeignBranches/Subversion,
123
 
for the current list of constraints.