← 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

  • Committer: Canonical.com Patch Queue Manager
  • Date: 2008-05-09 16:35:34 UTC
  • mfrom: (3418.1.1 ianc-integration)
  • Revision ID: pqm@pqm.ubuntu.com-20080509163534-t75i8ugsnro38rsh
Add plugin and integration chapters to User Guide (Ian Clatworthy)

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
 
 
23
A simple example
 
24
----------------
 
25
 
 
26
Here's a simple example of how you can use bzr-svn to hack on a
 
27
GNOME project like **beagle**. Firstly, setup a local shared repository
 
28
for storing your branches in and checkout the trunk::
 
29
 
 
30
  bzr init-repo --rich-root-pack beagle-repo
 
31
  cd beagle-repo
 
32
  bzr checkout svn+ssh://svn.gnome.org/svn/beagle/trunk beagle-trunk
 
33
 
 
34
Note that using the ``rich-root-pack`` option to ``init-repo`` is
 
35
important as bzr-svn requires some extra metadata not yet supported in Bazaar's
 
36
default repository format. Next, create a feature branch and hack away::
 
37
 
 
38
  bzr branch beagle-trunk beagle-feature1
 
39
  cd beagle-feature1
 
40
  *changes*
 
41
  bzr commit -m "blah blah blah"
 
42
  *changes*
 
43
  bzr commit -m "blah blah blah"
 
44
 
 
45
When the feature is cooked, refresh your trunk mirror and merge
 
46
your change::
 
47
 
 
48
  cd ../beagle-trunk
 
49
  bzr update
 
50
  bzr merge ../beagle-feature1
 
51
  bzr commit -m "Complete comment for SVN commit"
 
52
 
 
53
As your trunk mirror is a checkout, committing to it implicitly
 
54
commits to the real Subversion trunk. That's it!
 
55
 
 
56
 
 
57
Using a central repository mirror
 
58
---------------------------------
 
59
 
 
60
For large projects, it often makes sense to tweak the recipe given above.
 
61
In particular, the initial checkout can get quite slow so you may wish
 
62
to import the Subversion repository into a Bazaar one once and for all
 
63
for your project, and then branch from that native Bazaar repository
 
64
instead. bzr-svn provides the ``svn-import`` command for doing this
 
65
repository-to-repository conversion. See ``bzr help svn-import`` for details.
 
66
 
 
67
Here's the recipe from above updated to use a central Bazaar mirror::
 
68
 
 
69
  bzr init-repo --rich-root-pack beagle-repo
 
70
  cd beagle-repo
 
71
  bzr branch bzr+ssh://bzr.gnome.org/bzr/beagle/trunk beagle-trunk
 
72
  bzr branch beagle-trunk beagle-feature1
 
73
  cd beagle-feature1
 
74
  *changes*
 
75
  bzr commit -m "blah blah blah"
 
76
  *changes*
 
77
  bzr commit -m "blah blah blah"
 
78
  cd ../beagle-trunk
 
79
  bzr pull
 
80
  bzr merge ../beagle-feature1
 
81
  bzr commit -m "Complete comment for SVN commit"
 
82
  bzr svn-push
 
83
 
 
84
In this case, committing to the trunk only commits the merge locally.
 
85
To commit back to the master Subversion trunk, an additional command
 
86
(``bzr svn-push``) is required.
 
87
 
 
88
Note: You'll need to give ``pull and ``svn-push`` the relevant URLs
 
89
the first time you use those commands in the trunk branch. After that,
 
90
bzr remembers them.
 
91
 
 
92
The final piece of the puzzle in this setup is to put scripts in
 
93
place to keep the central Bazaar mirror synchronized with the Subversion
 
94
one. This can be done by adding a cron job, using a Subversion hook,
 
95
or whatever makes sense in your environment.
 
96
 
 
97
 
 
98
Limitations of bzr-svn
 
99
----------------------
 
100
 
 
101
Bazaar and Subversion are different tools with different capabilities
 
102
so there will always be some limited interoperability issues.
 
103
Here are some examples current as of bzr-svn 0.49:
 
104
 
 
105
 * Bazaar doesn't support versioned properties
 
106
 
 
107
 * Renames are not correctly communicated.
 
108
 
 
109
See the bzr-svn web page,
 
110
http://bazaar-vcs.org/BzrForeignBranches/Subversion,
 
111
for the current list of constraints.