1964.2.1
by John Arbash Meinel
Adding basic documentation about working with a central repository |
1 |
==================== |
2 |
Centralized Workflow |
|
3 |
==================== |
|
4 |
||
2098.2.3
by John Arbash Meinel
Switch to automatic numbering for sections and sub-sections. |
5 |
.. sectnum:: |
6 |
||
7 |
||
8 |
Overview |
|
9 |
======== |
|
2098.2.1
by John Arbash Meinel
Apply changes recommended by Alaa Salman |
10 |
|
11 |
This document describes a possible workflow for using Bazaar_. That of |
|
12 |
using Bazaar_, the distributed version control system, in a centralized |
|
13 |
manner. Bazaar_ is designed to be very flexible and allows several |
|
14 |
different workflows, from fully decentralized to mostly centralized. The |
|
15 |
workflow used here is meant to ease a new user into more advanced usage of |
|
16 |
Bazaar_, and allows them to work in a mix of centralized and decentralized |
|
17 |
operations. |
|
18 |
||
19 |
In general, this document is meant for users coming from a background of |
|
20 |
centralized version control systems such as CVS or subversion. It is |
|
21 |
common in work settings to have a single central server hosting the |
|
22 |
codebase, with several people working on this codebase, keeping their work |
|
23 |
in sync. This workflow is also applicable to a single developer working |
|
24 |
on several different machines. |
|
1964.2.1
by John Arbash Meinel
Adding basic documentation about working with a central repository |
25 |
|
26 |
.. _Bazaar: http://bazaar-vcs.org |
|
27 |
||
2098.2.4
by John Arbash Meinel
Include a table-of-contents. |
28 |
.. contents:: |
29 |
||
1964.2.1
by John Arbash Meinel
Adding basic documentation about working with a central repository |
30 |
|
2098.2.3
by John Arbash Meinel
Switch to automatic numbering for sections and sub-sections. |
31 |
Initial Setup |
32 |
============= |
|
1964.2.1
by John Arbash Meinel
Adding basic documentation about working with a central repository |
33 |
|
34 |
These are some reasonably simple steps to setup Bazaar_ so that it works |
|
35 |
well for you. |
|
36 |
||
37 |
||
2098.2.3
by John Arbash Meinel
Switch to automatic numbering for sections and sub-sections. |
38 |
Setting User Email |
39 |
------------------ |
|
1964.2.1
by John Arbash Meinel
Adding basic documentation about working with a central repository |
40 |
|
41 |
Your user identity is stored with each commit. While this doesn't have to |
|
2098.2.1
by John Arbash Meinel
Apply changes recommended by Alaa Salman |
42 |
be accurate or unique, it will be used in log messages and |
43 |
annotations, so it is better to have something real. |
|
44 |
||
45 |
:: |
|
46 |
||
47 |
% bzr whoami "John Doe <jdoe@organization.com>" |
|
48 |
||
49 |
||
2098.2.3
by John Arbash Meinel
Switch to automatic numbering for sections and sub-sections. |
50 |
Setting up a local Repository |
51 |
----------------------------- |
|
1964.2.1
by John Arbash Meinel
Adding basic documentation about working with a central repository |
52 |
|
53 |
Bazaar_ branches generally copy the history information around with them, |
|
54 |
which is part of how you can work in a fully decentralized manner. As an |
|
2098.2.1
by John Arbash Meinel
Apply changes recommended by Alaa Salman |
55 |
optimization, it is possible for related branches to combine their storage |
56 |
needs so that you do not need to copy around all of this history |
|
57 |
information whenever you create a new branch. |
|
1964.2.1
by John Arbash Meinel
Adding basic documentation about working with a central repository |
58 |
|
59 |
The best way to do this is to create a `Shared Repository`_. In general, |
|
60 |
branches will share their storage if they exist in a subdirectory of a |
|
2098.2.1
by John Arbash Meinel
Apply changes recommended by Alaa Salman |
61 |
`Shared Repository`_. So let's setup a `Shared Repository`_ in our home |
1964.2.1
by John Arbash Meinel
Adding basic documentation about working with a central repository |
62 |
directory, thus all branches we create underneath will share their history |
2098.2.1
by John Arbash Meinel
Apply changes recommended by Alaa Salman |
63 |
storage. |
64 |
||
65 |
:: |
|
1964.2.1
by John Arbash Meinel
Adding basic documentation about working with a central repository |
66 |
|
67 |
% bzr init-repo --trees ~ |
|
68 |
||
69 |
||
2098.2.3
by John Arbash Meinel
Switch to automatic numbering for sections and sub-sections. |
70 |
Setting up a remote Repository |
2098.2.1
by John Arbash Meinel
Apply changes recommended by Alaa Salman |
71 |
--------------------------------- |
72 |
||
73 |
Many times you want a location where data is stored separately from where |
|
74 |
you do your work. This workflow is required by centralized systems |
|
75 |
(CVS/SVN). Usually they are on separate machines, but not always. This is |
|
76 |
actually a pretty good setup, especially in a work environment. Since it |
|
77 |
ensures a central location where data can be backed up, and means that if |
|
78 |
something happens to a developer's machine, no committed work has to be |
|
79 |
lost. |
|
80 |
||
81 |
So let's set up a shared location for our project on a remote machine |
|
82 |
called ``centralhost``. Again, we will use a |
|
83 |
`Shared Repository`_ to optimize disk usage. |
|
84 |
||
85 |
:: |
|
1964.2.1
by John Arbash Meinel
Adding basic documentation about working with a central repository |
86 |
|
87 |
% bzr init-repo --no-trees sftp://centralhost/srv/bzr/ |
|
88 |
||
89 |
You can think of this step as similar to setting up a new cvsroot, or |
|
2098.2.1
by John Arbash Meinel
Apply changes recommended by Alaa Salman |
90 |
subversion repository. |
91 |
||
92 |
||
2098.2.3
by John Arbash Meinel
Switch to automatic numbering for sections and sub-sections. |
93 |
Versioning an existing project |
94 |
============================== |
|
2098.2.1
by John Arbash Meinel
Apply changes recommended by Alaa Salman |
95 |
|
96 |
Now that we have a repository, let's create a versioned project. Most of |
|
97 |
the time, you will already have some code that you are working with, |
|
1964.2.1
by John Arbash Meinel
Adding basic documentation about working with a central repository |
98 |
that you now want to version using Bazaar_. If the code was originally |
99 |
in source control, there are many ways to convert the project to Bazaar_ |
|
2098.2.1
by John Arbash Meinel
Apply changes recommended by Alaa Salman |
100 |
without losing any history. However, this is outside the scope of this |
101 |
document. See `Tracking Upstream`_ for some possibilities (section |
|
102 |
"Converting and keeping history"). |
|
103 |
||
104 |
.. _Tracking Upstream: http://bazaar-vcs.org/TrackingUpstream |
|
105 |
||
106 |
.. |
|
107 |
XXX: We really need a different document for discussing conversion of a |
|
108 |
project. Right now TrackingUpstream is the best we have, though. |
|
109 |
||
110 |
||
2098.2.3
by John Arbash Meinel
Switch to automatic numbering for sections and sub-sections. |
111 |
Developer 1: Creating the first revision |
112 |
---------------------------------------- |
|
1964.2.1
by John Arbash Meinel
Adding basic documentation about working with a central repository |
113 |
|
114 |
So first, we want to create a branch in our remote Repository, where we |
|
115 |
will want to host the project. Let's assume we have a project named |
|
2098.2.1
by John Arbash Meinel
Apply changes recommended by Alaa Salman |
116 |
"sigil" that we want to start versioning. |
117 |
||
118 |
:: |
|
1964.2.1
by John Arbash Meinel
Adding basic documentation about working with a central repository |
119 |
|
120 |
% bzr init sftp://centralhost/srv/bzr/sigil |
|
121 |
||
122 |
This can be thought of as the "HEAD" branch in CVS terms, or as the "trunk" |
|
2098.2.1
by John Arbash Meinel
Apply changes recommended by Alaa Salman |
123 |
in Subversion terms. We will call this the ``dev`` branch. |
1964.2.1
by John Arbash Meinel
Adding basic documentation about working with a central repository |
124 |
|
2098.2.1
by John Arbash Meinel
Apply changes recommended by Alaa Salman |
125 |
I prefer working in a subdirectory of my home directory to avoid collisions with all |
126 |
the other files that end up there. Also, we will want a project |
|
1964.2.1
by John Arbash Meinel
Adding basic documentation about working with a central repository |
127 |
directory where we can hold all of the different branches we end up |
2098.2.1
by John Arbash Meinel
Apply changes recommended by Alaa Salman |
128 |
working on. |
129 |
||
130 |
:: |
|
1964.2.1
by John Arbash Meinel
Adding basic documentation about working with a central repository |
131 |
|
132 |
% cd ~ |
|
133 |
% mkdir work |
|
134 |
% cd work |
|
135 |
% mkdir sigil |
|
136 |
% cd sigil |
|
137 |
% bzr checkout sftp://centralhost/srv/bzr/sigil dev |
|
138 |
% cd dev |
|
139 |
% cp -ar ~/sigil/* . |
|
140 |
% bzr add |
|
141 |
% bzr commit -m "Initial import of Sigil" |
|
142 |
||
2098.2.1
by John Arbash Meinel
Apply changes recommended by Alaa Salman |
143 |
|
144 |
In the example above, we created an empty branch (the ``/sigil`` branch) |
|
145 |
on ``centralhost``, and then checkout out this empty branch onto our |
|
146 |
workstation to add files from our existing project. |
|
147 |
There are many ways to setup your working directory, but the steps above |
|
148 |
make it easy to handle working with feature/bugfix branches. And one |
|
1964.2.1
by John Arbash Meinel
Adding basic documentation about working with a central repository |
149 |
of the strong points of Bazaar_ is how well it works with branches. |
150 |
||
151 |
At this point, because you have a 'checkout' of the remote branch, any |
|
2098.2.1
by John Arbash Meinel
Apply changes recommended by Alaa Salman |
152 |
commits you make in ``~/work/sigil/dev/`` will automatically be saved both locally, |
1964.2.1
by John Arbash Meinel
Adding basic documentation about working with a central repository |
153 |
and on ``centralhost``. |
154 |
||
155 |
||
2098.2.3
by John Arbash Meinel
Switch to automatic numbering for sections and sub-sections. |
156 |
Developer N: Getting a working copy of the project |
157 |
-------------------------------------------------- |
|
1964.2.1
by John Arbash Meinel
Adding basic documentation about working with a central repository |
158 |
|
159 |
Since the first developer did all of the work of creating the project, |
|
2098.2.1
by John Arbash Meinel
Apply changes recommended by Alaa Salman |
160 |
all other developers would just checkout that branch. **They should |
2098.2.3
by John Arbash Meinel
Switch to automatic numbering for sections and sub-sections. |
161 |
still follow** `Setting User Email`_ and `Setting up a local Repository`_. |
1964.2.1
by John Arbash Meinel
Adding basic documentation about working with a central repository |
162 |
|
2098.2.1
by John Arbash Meinel
Apply changes recommended by Alaa Salman |
163 |
To get a copy of the current development tree:: |
1964.2.1
by John Arbash Meinel
Adding basic documentation about working with a central repository |
164 |
|
165 |
% cd ~/work/sigil |
|
166 |
% bzr checkout sftp://centralhost/srv/bzr/sigil dev |
|
167 |
||
168 |
Now that two people both have a checkout of |
|
169 |
``sftp://centralhost/srv/bzr/sigil``, there will be times when one of |
|
2098.2.1
by John Arbash Meinel
Apply changes recommended by Alaa Salman |
170 |
the checkouts will be out of date with the current version. |
171 |
At commit time, Bazaar_ will inform the user of this and prevent them from |
|
172 |
committing. To get up to date, use ``bzr update`` to update the |
|
173 |
tree with the remote changes. This may require resolving conflicts, if the |
|
174 |
same files have been modified. |
|
175 |
||
176 |
||
2098.2.3
by John Arbash Meinel
Switch to automatic numbering for sections and sub-sections. |
177 |
Developing on separate branches |
178 |
=============================== |
|
1964.2.1
by John Arbash Meinel
Adding basic documentation about working with a central repository |
179 |
|
180 |
So far everyone is working and committing their changes into the same |
|
2098.2.1
by John Arbash Meinel
Apply changes recommended by Alaa Salman |
181 |
branch. This means that everyone needs to update fairly regularly and |
1964.2.1
by John Arbash Meinel
Adding basic documentation about working with a central repository |
182 |
deal with other people's changes. Also, if one person commits something |
2098.2.1
by John Arbash Meinel
Apply changes recommended by Alaa Salman |
183 |
that breaks the codebase, then upon syncing, everyone will get the |
184 |
problem. |
|
1964.2.1
by John Arbash Meinel
Adding basic documentation about working with a central repository |
185 |
|
2098.2.1
by John Arbash Meinel
Apply changes recommended by Alaa Salman |
186 |
Usually, it is better to do development on different branches, and then |
1964.2.1
by John Arbash Meinel
Adding basic documentation about working with a central repository |
187 |
integrate those back into the main branch, once they are stable. This is |
188 |
one of the biggest changes from working with CVS/SVN. They both allow you |
|
189 |
to work on separate branches, but their merging algorithms are fairly |
|
2098.2.1
by John Arbash Meinel
Apply changes recommended by Alaa Salman |
190 |
weak, so it is difficult to keep things synchronized. Bazaar_ tracks |
1964.2.1
by John Arbash Meinel
Adding basic documentation about working with a central repository |
191 |
what has already been merged, and can even apply changes to files that |
192 |
have been renamed. |
|
193 |
||
194 |
||
2098.2.3
by John Arbash Meinel
Switch to automatic numbering for sections and sub-sections. |
195 |
Creating and working on a new branch |
196 |
------------------------------------ |
|
1964.2.1
by John Arbash Meinel
Adding basic documentation about working with a central repository |
197 |
|
198 |
We want to keep our changes available for other people, even if they |
|
2098.2.1
by John Arbash Meinel
Apply changes recommended by Alaa Salman |
199 |
aren't quite complete yet. So we will create a new public branch on |
200 |
``centralhost``, and track it locally. |
|
201 |
||
202 |
:: |
|
1964.2.1
by John Arbash Meinel
Adding basic documentation about working with a central repository |
203 |
|
204 |
% cd ~/work/sigil |
|
205 |
% bzr branch sftp://centralhost/srv/bzr/sigil \ |
|
206 |
sftp://centralhost/srv/bzr/sigil/doodle-fixes |
|
207 |
% bzr checkout sftp://centralhost/srv/bzr/sigil/doodle-fixes doodle-fixes |
|
208 |
% cd doodle-fixes |
|
209 |
||
2098.2.1
by John Arbash Meinel
Apply changes recommended by Alaa Salman |
210 |
We now have a place to make any fixes we need to ``doodle``. And we would |
211 |
not interrupt people who are working on other parts of the code. Because |
|
212 |
we have a checkout, any commits made in the ``~/work/sigil/doodle-fixes/`` |
|
213 |
will also show up on ``centralhost``. [#nestedbranches]_ It is also |
|
214 |
possible to have 2 developers collaborate on one of these branches, just |
|
215 |
like they would have collaborated on the ``dev`` branch. [#cbranch]_ |
|
216 |
||
217 |
.. [#nestedbranches] It may look odd to have a branch in a subdirectory of |
|
218 |
another branch. This is just fine, and you can think of it as a |
|
219 |
heirarchial namespace. Where the nested branch is derived from the |
|
220 |
outer branch. |
|
1964.2.1
by John Arbash Meinel
Adding basic documentation about working with a central repository |
221 |
|
222 |
.. [#cbranch] When using lots of independent branches, having to retype |
|
223 |
the full URL all the time takes a lot of typing. We are looking into |
|
224 |
various methods to help with this, such as branch aliases, etc. For |
|
225 |
now, though, the bzrtools_ plugin provides the ``bzr cbranch`` command. |
|
226 |
Which is designed to take a base branch, create a new public branch, |
|
227 |
and create a checkout of that branch, all with much less typing. |
|
228 |
Configuring ``cbranch`` is outside the scope of this document, but the |
|
229 |
final commands look like ``bzr cbranch dev my-feature-branch`` |
|
230 |
||
231 |
.. _bzrtools: https://launchpad.net/products/bzrtools |
|
232 |
||
233 |
||
2098.2.3
by John Arbash Meinel
Switch to automatic numbering for sections and sub-sections. |
234 |
Merging changes back |
235 |
-------------------- |
|
1964.2.1
by John Arbash Meinel
Adding basic documentation about working with a central repository |
236 |
|
2098.2.1
by John Arbash Meinel
Apply changes recommended by Alaa Salman |
237 |
When it is decided that some of the changes in ``doodle-fixes`` are ready |
238 |
to be merged into the main branch, simply do:: |
|
1964.2.1
by John Arbash Meinel
Adding basic documentation about working with a central repository |
239 |
|
240 |
% cd ~/work/sigil/dev |
|
241 |
% bzr merge ../doodle-fixes |
|
242 |
||
2098.2.1
by John Arbash Meinel
Apply changes recommended by Alaa Salman |
243 |
Now the changes are available in the ``dev`` branch, but they have not |
244 |
been committed yet. This is the time when you want to review the final |
|
245 |
changes, and double check the code to make sure it compiles cleanly and |
|
246 |
passes the test suite. The commands ``bzr status`` and ``bzr diff`` are |
|
247 |
good tools to use here. Also, this is the time to resolve any conflicts. |
|
248 |
Bazaar_ will prevent you from committing until you have resolved these |
|
249 |
conflicts. That way you don't accidentally commit the conflict markers. |
|
250 |
The command ``bzr status`` will show the conflicts along with the other |
|
251 |
changes, or you can use ``bzr conflicts`` to just list conflicts. Use |
|
252 |
``bzr resolve file/name`` or ``bzr resolve --all`` once conflicts have |
|
253 |
been handled. [#resolve]_ If you have a conflict that is particularly |
|
254 |
difficult to solve you may want to use the ``bzr remerge`` command. It |
|
255 |
will let you try different merge algorithms, as well as let you see the |
|
256 |
original source lines (``--show-base``). |
|
1964.2.1
by John Arbash Meinel
Adding basic documentation about working with a central repository |
257 |
|
258 |
.. [#resolve] Some systems make you resolve conflicts as part of the merge |
|
259 |
process. We have found that it is usually easier to resolve conflicts |
|
260 |
when you have the view of the entire tree, rather than just a single |
|
261 |
file. It gives you much more context, and also lets you run tests as |
|
262 |
you resolve the problems. |
|
263 |
||
264 |
||
2098.2.3
by John Arbash Meinel
Switch to automatic numbering for sections and sub-sections. |
265 |
Recommended Branching |
266 |
--------------------- |
|
1964.2.1
by John Arbash Meinel
Adding basic documentation about working with a central repository |
267 |
|
268 |
One very common way to handle all of these branches is to give each |
|
269 |
developer their own branch, and their own place to work in the central |
|
270 |
location. This can be done with:: |
|
271 |
||
272 |
% bzr branch sftp://centralhost/srv/bzr/sigil \ |
|
273 |
sftp://centralhost/srv/bzr/sigil/user-a |
|
274 |
% bzr branch sftp://centralhost/srv/bzr/sigil \ |
|
275 |
sftp://centralhost/srv/bzr/sigil/user-b |
|
276 |
||
277 |
This gives each developer their own branch to work on. And, they can |
|
278 |
easily create a new feature branch for themselves with just[#cbranch]_:: |
|
279 |
||
280 |
% bzr branch sftp://centralhost/srv/bzr/sigil/user-a \ |
|
281 |
sftp://centralhost/srv/bzr/sigil/user-a/feature |
|
282 |
% cd ~/work/sigil |
|
283 |
% bzr checkout sftp://centralhost/srv/bzr/sigil/user-a/feature myfeature |
|
284 |
||
285 |
||
2098.2.3
by John Arbash Meinel
Switch to automatic numbering for sections and sub-sections. |
286 |
Glossary |
287 |
======== |
|
1964.2.1
by John Arbash Meinel
Adding basic documentation about working with a central repository |
288 |
|
289 |
Shared Repository |
|
290 |
----------------- |
|
291 |
||
2098.2.2
by John Arbash Meinel
minor cleanup |
292 |
Bazaar_ has the concept of a "Shared Repository". This is similar to the |
1964.2.1
by John Arbash Meinel
Adding basic documentation about working with a central repository |
293 |
concept of other RCS's repository. Such as in Subversion, where you have a |
294 |
remote repository, which is where all of the history is stored, and |
|
295 |
locally you don't have any history information, only a checkout of the |
|
296 |
working tree files. Note that "Shared" in this context means shared |
|
297 |
between branches. It *may* be shared between people, but standalone |
|
298 |
branches can also be shared between people. |
|
299 |
||
2098.2.2
by John Arbash Meinel
minor cleanup |
300 |
In Bazaar_ terms, a "Shared Repository" is a location where multiple |
1964.2.1
by John Arbash Meinel
Adding basic documentation about working with a central repository |
301 |
branches can **share** their revision history information. Because Bazaar_ |
302 |
wants to support decentralized workflows, it is possible for every branch |
|
303 |
to maintain its own revision history information. But this is often |
|
2098.2.1
by John Arbash Meinel
Apply changes recommended by Alaa Salman |
304 |
inefficient, since related branches share history, and they might as well |
1964.2.1
by John Arbash Meinel
Adding basic documentation about working with a central repository |
305 |
share the storage as well. |
306 |
||
307 |
||
308 |
.. |
|
309 |
vim: tw=74 ft=rst spell spelllang=en_us |