← Back to branch summary

~bzr-pqm/bzr/bzr.dev

« back to all changes in this revision

Viewing changes to bzrlib/help_topics.py

  • Committer: Canonical.com Patch Queue Manager
  • Date: 2007-05-24 16:07:00 UTC
  • mfrom: (2491.1.1 jam-integration)
  • Revision ID: pqm@pqm.ubuntu.com-20070524160700-3mu8f24yc5ej88m1
(James Westby) Add a help topic for working trees and repositories.

Show diffs side-by-side

added added

removed removed

Lines of Context:
bzrlib/help_topics.py
276
276
              commits are only made locally
277
277
"""
278
278
 
 
279
_repositories = \
 
280
"""Repositories
 
281
 
 
282
Repositories in Bazaar are where committed information is stored. It is
 
283
possible to create a shared repository which allows multiple branches to
 
284
share their information in the same location. When a new branch is
 
285
created it will first look to see if there is a containing repository it
 
286
can share.
 
287
 
 
288
When two branches of the same project share a repository, there is
 
289
generally a large space saving. For some operations (e.g. branching
 
290
within the repository) this translates in to a large time saving.
 
291
 
 
292
To create a shared repository use the init-repository command (or the alias
 
293
init-repo). This command takes the location of the repository to create. This
 
294
means that 'bzr init-repository repo' will create a directory named 'repo',
 
295
which contains a shared repository. Any new branches that are created in this
 
296
directory will then use it for storage.
 
297
 
 
298
It is a good idea to create a repository whenever you might create more
 
299
than one branch of a project. This is true for both working areas where you
 
300
are doing the development, and any server areas that you use for hosting
 
301
projects. In the latter case, it is common to want branches without working
 
302
trees. Since the files in the branch will not be edited directly there is no
 
303
need to use up disk space for a working tree. To create a repository in which
 
304
the branches will not have working trees pass the '--no-trees' option to
 
305
'init-repository'.
 
306
 
 
307
Related commands:
 
308
 
 
309
  init-repository   Create a shared repository. Use --no-trees to create one
 
310
                    in which new branches won't get a working tree.
 
311
"""
 
312
 
 
313
 
 
314
_working_trees = \
 
315
"""Working Trees
 
316
 
 
317
A working tree is the contents of a branch placed on disk so that you can
 
318
see the files and edit them. The working tree is where you make changes to a
 
319
branch, and when you commit the current state of the working tree is the
 
320
snapshot that is recorded in the commit.
 
321
 
 
322
When you push a branch to a remote system, a working tree will not be
 
323
created. If one is already present the files will not be updated. The
 
324
branch information will be updated and the working tree will be marked
 
325
as out-of-date. Updating a working tree remotely is difficult, as there
 
326
may be uncommitted changes or the update may cause content conflicts that are
 
327
difficult to deal with remotely.
 
328
 
 
329
If you have a branch with no working tree you can use the 'checkout' command
 
330
to create a working tree. If you run 'bzr checkout .' from the branch it will
 
331
create the working tree. If the branch is updated remotely, you can update the
 
332
working tree by running 'bzr update' in that directory.
 
333
 
 
334
If you have a branch with a working tree that you do not want the 'remove-tree'
 
335
command will remove the tree if it is safe. This can be done to avoid the
 
336
warning about the remote working tree not being updated when pushing to the
 
337
branch. It can also be useful when working with a '--no-trees' repository
 
338
(see 'bzr help repositories').
 
339
 
 
340
If you want to have a working tree on a remote machine that you push to you
 
341
can either run 'bzr update' in the remote branch after each push, or use some
 
342
other method to update the tree during the push. There is an 'rspush' plugin
 
343
that will update the working tree using rsync as well as doing a push. There
 
344
is also a 'push-and-update' plugin that automates running 'bzr update' via SSH
 
345
after each push.
 
346
 
 
347
Useful commands:
 
348
 
 
349
  checkout     Create a working tree when a branch does not have one.
 
350
  remove-tree  Removes the working tree from a branch when it is safe to do so.
 
351
  update       When a working tree is out of sync with it's associated branch
 
352
               this will update the tree to match the branch.
 
353
"""
 
354
 
279
355
 
280
356
topic_registry.register("revisionspec", _help_on_revisionspec,
281
357
                        "Explain how to use --revision")
295
371
    from bzrlib import bugtracker
296
372
    return bugtracker.tracker_registry.help_topic(topic)
297
373
topic_registry.register('bugs', get_bugs_topic, 'Bug tracker support')
 
374
topic_registry.register('repositories', _repositories,
 
375
                        'Basic information on shared repositories.')
 
376
topic_registry.register('working-trees', _working_trees,
 
377
                        'Information on working trees')
298
378
 
299
379
 
300
380
class HelpTopicIndex(object):
355
435
    def get_help_topic(self):
356
436
        """Return the help topic this can be found under."""
357
437
        return self.topic
 
438