← Back to branch summary

~bzr-pqm/bzr/bzr.dev

« back to all changes in this revision

Viewing changes to bzrlib/help_topics.py

  • Committer: James Westby
  • Date: 2007-02-02 00:16:10 UTC
  • mto: (2270.1.1 jam-integration)
  • mto: This revision was merged to the branch mainline in revision 2273.
  • Revision ID: jw+debian@jameswestby.net-20070202001610-rgff0g0w3my07ymj
Add a help topic describing checkouts and how they work.

It's meant to be an overview of what they are and what they might be useful
for, as well as a pointer to the commands that you need to manipulate them.

Show diffs side-by-side

added added

removed removed

Lines of Context:
bzrlib/help_topics.py
151
151
Note: --version must be supplied before any command.
152
152
"""
153
153
 
 
154
_checkouts = \
 
155
"""Checkouts
 
156
 
 
157
Checkouts are a way of working with Bazaar that can be quite simple, but also
 
158
very useful, as they allow you to ignore some of the features of distributed
 
159
version control that Bazaar has until you need them. Using them can give you
 
160
a workflow that is very similar to SVN, but still allow others working on
 
161
the project to use another workflow, allow you flexibility in your own
 
162
workflow, and still provide some of the improvements of Bazaar over SVN to
 
163
you.
 
164
 
 
165
A checkout is created with the bzr checkout command (see "help checkout").
 
166
You pass it a reference to another branch, and it will create a local branch
 
167
for you that still contains a reference to the branch you created the
 
168
checkout from (the master branch). Then if you commit any changes to your local
 
169
branch those commits will be made on the other branch first. This creates an
 
170
instant mirror of your work, or facilitates lockstep development, where each
 
171
developer is working together, continuously integrating the changes of others.
 
172
 
 
173
However the checkout is still a first class branch in Bazaar terms, so that
 
174
you have the full history locally, and can branch from it, for example to
 
175
work on a feature branch.
 
176
 
 
177
As you have a first class branch you can also commit locally if you want,
 
178
for instance due to the temporary loss af a network connection. Use the
 
179
--local option to commit to do this.
 
180
 
 
181
If you are using a checkout from a shared branch you will periodically want to
 
182
pull in all the changes made by others. This is done using the "update"
 
183
command. The changes need to be pulled before any commit, but Bazaar will tell
 
184
you if there are any changes and suggest that you use this command when needed.
 
185
 
 
186
It is also possible to create a "lightweight" checkout by passing the
 
187
--lightweight flag to checkout. A lightweight checkout is even closer to an
 
188
SVN checkout in that it is not a first class branch, it mainly consists of the
 
189
working tree. This means that any history operations must query the master
 
190
branch, which could be slow if a network connection is involved. Also, as you
 
191
don't have a local branch, then you cannot commit locally.
 
192
 
 
193
Obviously to commit on a checkout you need to be able to write to the master
 
194
branch. This means that there must be a writeable transport in between, such
 
195
as sftp://, and that you have write permissions at the other end. Checkouts
 
196
also work on the local file system, so that all that matters is file
 
197
permissions.
 
198
 
 
199
You can change the master of a checkout by using the "bind" command (see "help
 
200
bind"). This will change the location that the commits are sent to. The bind
 
201
command can also be used to turn a branch in to a heavy checkout. If you
 
202
would like to convert your heavy checkout to a normal branch so that every
 
203
commit is local you can use the "unbind" command.
 
204
 
 
205
Useful commands:
 
206
 
 
207
  checkout    Create a checkout. Pass --lightweight to get a lightweight
 
208
              checkout
 
209
  update      Pull any changes in the master branch in to your checkout
 
210
  commit      Make a commit that is sent to the master branch. If you have
 
211
              a heavy checkout then the --local option will commit to the 
 
212
              checkout without sending the commit to the master
 
213
  bind        Change the master branch that the commits in the checkout will
 
214
              be sent to
 
215
  unbind      Turn a heavy checkout into a standalone branch so that any
 
216
              commits are only made locally
 
217
"""
 
218
 
154
219
 
155
220
topic_registry.register("revisionspec", _help_on_revisionspec,
156
221
                        "Explain how to use --revision")
162
227
topic_registry.register('formats', get_format_topic, 'Directory formats')
163
228
topic_registry.register('global-options', _global_options,
164
229
                        'Options that can be used with any command')
 
230
topic_registry.register('checkouts', _checkouts,
 
231
                        'Information on what a checkout is')
 
232