Bazaar

Merge lp:~mbp/bzr/help into lp:bzr

  1. help
  2. Merge into bzr.dev
Proposed by Martin Pool
Status: Work in progress
Proposed branch: lp:~mbp/bzr/help
Merge into: lp:bzr
Diff against target: 121 lines (+53/-32)
1 file modified
bzrlib/builtins.py (+53/-32)
To merge this branch: bzr merge lp:~mbp/bzr/help
Reviewer Review Type Date Requested Status
Jonathan Riddell (community) Needs Fixing
Review via email: mp+61793@code.launchpad.net

Description of the change

Better help for update and revert. (Thanks Maritza.)

To post a comment you must log in.
Revision history for this message
Jonathan Riddell (jr) wrote :

typo: "Update the a working tree"

Reply
Revision history for this message
Jonathan Riddell (jr) wrote :

"the tree's branch has changed and the tree is out of date: 'bzr commit' may tell you this."

This doesn't read quite right to me, the colon suggests to me that bzr commit is a course of action to take whereas the intention is to indicate that is will already have been run

I'd use

"the tree's branch has changed and the tree is out of date, 'bzr commit' may have warned you of this."

Reply
Revision history for this message
Martin Pool (mbp) wrote :

good idea.

Reply
Revision history for this message
Jonathan Riddell (jr) wrote :

"Revert changes files from a working tree" -> "Revert changed files from a working tree"

Reply
Revision history for this message
Jonathan Riddell (jr) wrote :

"you wish to temporarily revisit an old revision, or" might be nicer if this specified that it needs the -r flag
"you wish to temporarily revisit an old revision using '-r ARG', or"

Inconsistent quotes? Some places use ' some `` and one "

review: Needs Fixing
Reply
Revision history for this message
Wouter van Heyst (larstiq) wrote :

On Fri, May 20, 2011 at 16:01:42 -0000, Martin Pool wrote:
> Martin Pool has proposed merging lp:~mbp/bzr/help into lp:bzr.
>
> Requested reviews:
> bzr-core (bzr-core)
>
> For more details, see:
> https://code.launchpad.net/~mbp/bzr/help/+merge/61793
>
> Better help for update and revert. (Thanks Maritza.)

I like the new text! It has a couple of mentions of 'basis revision',
which might not be clear. Is there user explanation for that somewhere?
A quick grep doesn't find it, but perhaps I worry overly.

update has:

> + The new basis revision is by default the tip of the tree's branch, or
...

> + Any uncommitted changes in the working tree relative to the current basis
> + revision are carried across, by merging them into the new basis revision.

and revert:
> + Revert changes files from a working tree (or by default the whole tree) to be
> + the same as the files in the basis revision of the tree (or whatever revision
> + is specified with -r.)

Wouter van Heyst

Reply
Revision history for this message
Vincent Ladeuil (vila) wrote :

Can a native English speaker integrates all the useful remarks in that already well improved text ?

Reply
Revision history for this message
Martin Pool (mbp) wrote :

I will, I've just been away.

Reply

Unmerged revisions

5906. By Martin Pool

Better help for cmd_revert.

5905. By Martin Pool

Better help for cmd_update

Preview Diff

[H/L] Next/Prev Comment, [J/K] Next/Prev File, [N/P] Next/Prev Hunk
=== modified file 'bzrlib/builtins.py'
--- bzrlib/builtins.py 2011-05-18 12:18:39 +0000
+++ bzrlib/builtins.py 2011-05-20 16:02:21 +0000
@@ -1429,23 +1429,28 @@
14291429
14301430
1431class cmd_update(Command):1431class cmd_update(Command):
1432 __doc__ = """Update a tree to have the latest code committed to its branch.1432 __doc__ = """Update the a working tree to be based on a new revision.
14331433
1434 This will perform a merge into the working tree, and may generate1434 The new basis revision is by default the tip of the tree's branch, or
1435 conflicts. If you have any local changes, you will still1435 whatever is specified by the --revision option. If the tree's branch is
1436 need to commit them after the update for the update to be complete.1436 bound to a master branch, it will update the branch from the master, and
14371437 then update the working tree.
1438 If you want to discard your local changes, you can just do a1438
1439 'bzr revert' instead of 'bzr commit' after the update.1439 Any uncommitted changes in the working tree relative to the current basis
1440 revision are carried across, by merging them into the new basis revision.
1441 This merge may generate conflicts, in which case you may have to resolve
1442 them before doing other work.
1443
1444 Use 'bzr update' when:
1445 * you wish to temporarily revisit an old revision, or
1446 * the tree's branch has changed and the tree is out of date: 'bzr
1447 commit' may tell you this.
14401448
1441 If you want to restore a file that has been removed locally, use1449 If you want to restore a file that has been removed locally, use
1442 'bzr revert' instead of 'bzr update'.1450 'bzr revert' instead of 'bzr update'.
1443
1444 If the tree's branch is bound to a master branch, it will also update
1445 the branch from the master.
1446 """1451 """
14471452
1448 _see_also = ['pull', 'working-trees', 'status-flags']1453 _see_also = ['pull', 'working-trees', 'status-flags', 'conflicts', 'resolve']
1449 takes_args = ['dir?']1454 takes_args = ['dir?']
1450 takes_options = ['revision',1455 takes_options = ['revision',
1451 Option('show-base',1456 Option('show-base',
@@ -4300,17 +4305,33 @@
43004305
43014306
4302class cmd_revert(Command):4307class cmd_revert(Command):
4303 __doc__ = """Revert files to a previous revision.4308 __doc__ = """Revert working tree files to a previous revision.
43044309
4305 Giving a list of files will revert only those files. Otherwise, all files4310 Revert changes files from a working tree (or by default the whole tree) to be
4306 will be reverted. If the revision is not specified with '--revision', the4311 the same as the files in the basis revision of the tree (or whatever revision
4307 last committed revision is used.4312 is specified with -r.)
43084313
4309 To remove only some changes, without reverting to a prior version, use4314 Uses for 'bzr revert':
4310 merge instead. For example, "merge . -r -2..-3" (don't forget the ".")4315 * You have made changes in the working tree, and want to discard your
4311 will remove the changes introduced by the second last commit (-2), without4316 changes and go back to the previously-committed tree.
4312 affecting the changes introduced by the last commit (-1). To remove4317 * You have started a merge and not yet committed it, and you want to
4313 certain changes on a hunk-by-hunk basis, see the shelve command.4318 discard the work done towards it.
4319 * You want to undo all the changes made in a file and to take it back
4320 to exactly the text it had in a previous version.
4321 * Use the 'revert --forget-merges' to clear the pending-merge list,
4322 without reverting the tree.
4323
4324 Instead of 'bzr revert':
4325 * Use 'bzr update' if you want to temporarily revisit a previous
4326 revision.
4327 * Use 'bzr merge' with a reversed revision range if you want to undo
4328 only some changes to a file. For example, "merge . -r -2..-3" (don't
4329 forget the ".") will remove the changes introduced by the second last
4330 commit (-2), without affecting the changes introduced by the last
4331 commit (-1).
4332 * Use 'bzr shelve' to remove just some changes on a hunk-by-hunk basis.
4333 * Use 'bzr clean-tree' to delete unversioned or ignored files from the
4334 tree.
43144335
4315 By default, any files that have been manually changed will be backed up4336 By default, any files that have been manually changed will be backed up
4316 first. (Files changed only by merge are not backed up.) Backup files have4337 first. (Files changed only by merge are not backed up.) Backup files have
@@ -4326,14 +4347,14 @@
4326 created as above. Directories containing unknown files will not be4347 created as above. Directories containing unknown files will not be
4327 deleted.4348 deleted.
43284349
4329 The working tree contains a list of revisions that have been merged but4350 The working tree contains a list of 'pending merged' revisions that have
4330 not yet committed. These revisions will be included as additional parents4351 been merged but not yet committed. These revisions will be included as
4331 of the next commit. Normally, using revert clears that list as well as4352 additional parents of the next commit. Normally, using revert clears that
4332 reverting the files. If any files are specified, revert leaves the list4353 list as well as reverting the files. If any files are specified, revert
4333 of uncommitted merges alone and reverts only the files. Use ``bzr revert4354 leaves the list of uncommitted merges alone and reverts only the files.
4334 .`` in the tree root to revert all files but keep the recorded merges,4355 Use ``bzr revert .`` in the tree root to revert all files but keep the
4335 and ``bzr revert --forget-merges`` to clear the pending merge list without4356 recorded merges, and ``bzr revert --forget-merges`` to clear the pending
4336 reverting any files.4357 merge list without reverting any files.
43374358
4338 Using "bzr revert --forget-merges", it is possible to apply all of the4359 Using "bzr revert --forget-merges", it is possible to apply all of the
4339 changes from a branch in a single revision. To do this, perform the merge4360 changes from a branch in a single revision. To do this, perform the merge
@@ -4346,7 +4367,7 @@
4346 target branches.4367 target branches.
4347 """4368 """
43484369
4349 _see_also = ['cat', 'export', 'merge', 'shelve']4370 _see_also = ['cat', 'export', 'merge', 'shelve', 'clean-tree', 'update']
4350 takes_options = [4371 takes_options = [
4351 'revision',4372 'revision',
4352 Option('no-backup', "Do not save backups of reverted files."),4373 Option('no-backup', "Do not save backups of reverted files."),