← Back to branch summary

~bzr-pqm/bzr/bzr.dev

« back to all changes in this revision

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

  • Committer: Alexander Belchenko
  • Date: 2006-07-30 16:43:12 UTC
  • mto: (1711.2.111 jam-integration)
  • mto: This revision was merged to the branch mainline in revision 1906.
  • Revision ID: bialix@ukr.net-20060730164312-b025fd3ff0cee59e
rename  gpl.txt => COPYING.txt

Show diffs side-by-side

added added

removed removed

Lines of Context:
doc/en/user-guide/organizing_your_workspace.txt
1
 
Organizing your workspace
2
 
=========================
3
 
 
4
 
Common workspace layouts
5
 
------------------------
6
 
 
7
 
The best way for a Bazaar user to organize their workspace for a project
8
 
depends on numerous factors including:
9
 
 
10
 
* user role: project owner vs core developer vs casual contributor
11
 
 
12
 
* workflows: particularly the workflow the project encourages/mandates
13
 
  for making contributions
14
 
 
15
 
* size: large projects have different resource requirements to small ones.
16
 
 
17
 
There are at least 4 common ways of organizing one's workspace:
18
 
 
19
 
* lightweight checkout
20
 
* standalone tree
21
 
* feature branches
22
 
* switchable sandbox.
23
 
 
24
 
A brief description of each layout follows.
25
 
 
26
 
 
27
 
Lightweight checkout
28
 
--------------------
29
 
 
30
 
In this layout, the working tree is local and the branch is remote.
31
 
This is the standard layout used by CVS and Subversion: it's simple
32
 
and well understood.
33
 
 
34
 
To set up::
35
 
 
36
 
  bzr checkout --lightweight URL project
37
 
  cd project
38
 
 
39
 
To work::
40
 
 
41
 
  (make changes)
42
 
  bzr commit
43
 
  (make changes)
44
 
  bzr commit
45
 
 
46
 
Note that each commit implicitly publishes the change to everyone else
47
 
working from that branch. However, you need to be up to date with changes
48
 
in the remote branch for the commit to succeed. To grab the latest code
49
 
and merge it with your changes, if any::
50
 
 
51
 
  bzr update
52
 
 
53
 
 
54
 
Standalone tree
55
 
---------------
56
 
 
57
 
In this layout, the working tree & branch are in the one place. Unless
58
 
a shared repository exists in a higher level directory, the repository
59
 
is located in that same place as well. This is the default layout in
60
 
Bazaar and it's great for small to moderately sized projects.
61
 
 
62
 
To set up::
63
 
 
64
 
  bzr branch URL project
65
 
  cd project
66
 
 
67
 
To work::
68
 
 
69
 
  (make changes)
70
 
  bzr commit
71
 
  (make changes)
72
 
  bzr commit
73
 
 
74
 
To publish changes to a central location::
75
 
 
76
 
  bzr push [URL]
77
 
 
78
 
The URL for push is only required the first time.
79
 
 
80
 
If the central location has, in the meantime, received changes from
81
 
other users, then you'll need to merge those changes into your local
82
 
branch before you try to push again::
83
 
 
84
 
  bzr merge
85
 
  (resolve conflicts)
86
 
  bzr commit
87
 
 
88
 
As an alternative, a checkout can be used. Like a branch, a checkout
89
 
has a full copy of the history stored locally but the local branch
90
 
is bound to the remote location so that commits are published to
91
 
both locations at once.
92
 
 
93
 
Note: A checkout is actually smarter than a local commit followed by
94
 
a push. In particular, a checkout wil commit to the remote location
95
 
first and only commit locally if the remote commit succeeds.
96
 
 
97
 
 
98
 
Feature branches
99
 
----------------
100
 
 
101
 
In this layout, there are multiple branches/trees, typically sharing
102
 
a repository. One branch is kept as a mirror of "trunk" and each
103
 
unit-of-work (i.e. bug-fix or enhancement) gets its own "feature branch".
104
 
This layout is ideal for most projects, particularly moderately sized ones.
105
 
 
106
 
To set up::
107
 
 
108
 
  bzr init-repo project
109
 
  cd project
110
 
  bzr branch URL trunk
111
 
 
112
 
To start a feature branch::
113
 
 
114
 
  bzr branch trunk featureX
115
 
  cd featureX
116
 
 
117
 
To work::
118
 
 
119
 
  (make changes)
120
 
  bzr commit
121
 
  (make changes)
122
 
  bzr commit
123
 
 
124
 
To publish changes to a mailing list for review & approval::
125
 
 
126
 
  bzr send
127
 
 
128
 
To publish changes to a public branch (that can then be registered as
129
 
a Launchpad merge request, say)::
130
 
 
131
 
  bzr push [URL]
132
 
 
133
 
As a variation, the trunk can be created as a checkout. If you have
134
 
commit privileges on trunk, that lets you merge into trunk and the
135
 
commit of the merge will implicitly publish your change. Alternatively,
136
 
if the trunk URL is read-only (e.g. a http address), that prevents
137
 
accidental submission this way - ideal if the project workflow uses
138
 
an automated gatekeeper like PQM, say.
139
 
 
140
 
 
141
 
Local sandbox
142
 
-------------
143
 
 
144
 
This layout is very similar to the feature branches layout except that
145
 
the feature branches share a single working tree rather than having one
146
 
each. This is similar to git's default layout and it's useful for projects
147
 
with really large trees (> 10000 files say) or for projects with lots of
148
 
build artifacts (like .o or .class files).
149
 
 
150
 
To set up::
151
 
 
152
 
  bzr init-repo --no-trees project
153
 
  cd project
154
 
  bzr branch URL trunk
155
 
  bzr checkout --lightweight trunk sandbox
156
 
  cd sandbox
157
 
 
158
 
While you *could* start making changes in sandbox now, committing while
159
 
the sandbox is pointing to the trunk would mean that trunk is no longer
160
 
a mirror of the upstream URL (well unless the trunk is a checkout).
161
 
Therefore, you usually want to immediately create a feature branch and
162
 
switch your sandbox to it like this::
163
 
 
164
 
  bzr branch ../trunk ../featureX
165
 
  bzr switch ../featureX
166
 
 
167
 
The processes for making changes and submitting them are otherwise
168
 
pretty much the same as those used for feature branches.
169
 
 
170
 
 
171
 
Advanced layouts
172
 
----------------
173
 
 
174
 
If you wish, you can put together your own layout based on how **you** like
175
 
things organized. See `Advanced shared repository layouts
176
 
<shared_repository_layouts.html>`_ for examples and inspiration.