Rev 2413: (Ian Clatworthy) Help text fixes for add, commit, and export in file:///home/pqm/archives/thelove/bzr/%2Btrunk/

[Canonical.com Patch Queue Manager]

At file:///home/pqm/archives/thelove/bzr/%2Btrunk/

------------------------------------------------------------
revno: 2413
revision-id: pqm at pqm.ubuntu.com-20070412150356-jeie6iap22sae8xf
parent: pqm at pqm.ubuntu.com-20070412141938-72ysaak1x6brlfmm
parent: john at arbash-meinel.com-20070412143944-w1tdz5wvpaf6791p
committer: Canonical.com Patch Queue Manager<pqm at pqm.ubuntu.com>
branch nick: +trunk
timestamp: Thu 2007-04-12 16:03:56 +0100
message:
  (Ian Clatworthy) Help text fixes for add, commit, and export
modified:
  bzrlib/builtins.py             builtins.py-20050830033751-fc01482b9ca23183
    ------------------------------------------------------------
    revno: 2371.1.2
    merged: john at arbash-meinel.com-20070412143944-w1tdz5wvpaf6791p
    parent: john at arbash-meinel.com-20070322190703-qx2xft42j64hfp88
    parent: ian.clatworthy at internode.on.net-20070412060957-m8l5xx0cte108s3d
    committer: John Arbash Meinel <john at arbash-meinel.com>
    branch nick: jam-integration
    timestamp: Thu 2007-04-12 09:39:44 -0500
    message:
      (Ian Clatworthy) Help text fixes for add, commit, and export
    ------------------------------------------------------------
    revno: 2374.1.6
    merged: ian.clatworthy at internode.on.net-20070412060957-m8l5xx0cte108s3d
    parent: ian.clatworthy at internode.on.net-20070412060105-p8xvixkc0or94nxp
    committer: Ian Clatworthy <ian.clatworthy at internode.on.net>
    branch nick: bzr.help-fixes
    timestamp: Thu 2007-04-12 16:09:57 +1000
    message:
      explained selected fail commit failure by design
    ------------------------------------------------------------
    revno: 2374.1.5
    merged: ian.clatworthy at internode.on.net-20070412060105-p8xvixkc0or94nxp
    parent: ian.clatworthy at internode.on.net-20070402011840-ad1dombhee1vr88x
    committer: Ian Clatworthy <ian.clatworthy at internode.on.net>
    branch nick: bzr.help-fixes
    timestamp: Thu 2007-04-12 16:01:05 +1000
    message:
      explained selected fail commit failure by design
    ------------------------------------------------------------
    revno: 2374.1.4
    merged: ian.clatworthy at internode.on.net-20070402011840-ad1dombhee1vr88x
    parent: ian.clatworthy at internode.on.net-20070329091803-1774b7u9isk2z0p4
    committer: Ian Clatworthy <ian.clatworthy at internode.on.net>
    branch nick: bzr.quick
    timestamp: Mon 2007-04-02 11:18:40 +1000
    message:
      Include feedback from mailing list.
    ------------------------------------------------------------
    revno: 2374.1.3
    merged: ian.clatworthy at internode.on.net-20070329091803-1774b7u9isk2z0p4
    parent: ian.clatworthy at internode.on.net-20070327003529-dwroi8lgq0nxouov
    committer: Ian Clatworthy <ian.clatworthy at internode.on.net>
    branch nick: bzr.quick
    timestamp: Thu 2007-03-29 19:18:03 +1000
    message:
      Minor man page fixes for add, commit, export
=== modified file 'bzrlib/builtins.py'
--- a/bzrlib/builtins.py	2007-04-11 04:48:55 +0000
+++ b/bzrlib/builtins.py	2007-04-12 15:03:56 +0000
@@ -244,6 +244,8 @@
 
     Since a lightweight checkout is little more than a working tree
     this will refuse to run against one.
+
+    To re-create the working tree, use "bzr checkout".
     """
 
     takes_args = ['location?']
@@ -339,7 +341,11 @@
 
     --file-ids-from will try to use the file ids from the supplied path.
     It looks up ids trying to find a matching parent directory with the
-    same filename, and then by pure path.
+    same filename, and then by pure path. This option is rarely needed
+    but can be useful when adding the same logical file into two
+    branches that will be merged later (without showing the two different
+    adds as a conflict). It is also useful when merging another project
+    into a subdirectory of this one.
     """
     takes_args = ['file*']
     takes_options = ['no-recurse', 'dry-run', 'verbose',
@@ -1915,13 +1921,14 @@
     given, try to find the format with the extension. If no extension
     is found exports to a directory (equivalent to --format=dir).
 
-    Root may be the top directory for tar, tgz and tbz2 formats. If none
-    is given, the top directory will be the root name of the file.
+    If root is supplied, it will be used as the root directory inside
+    container formats (tar, zip, etc). If it is not supplied it will default
+    to the exported filename. The root option has no effect for 'dir' format.
 
     If branch is omitted then the branch containing the current working
     directory will be used.
 
-    Note: export of tree with non-ascii filenames to zip is not supported.
+    Note: Export of tree with non-ASCII filenames to zip is not supported.
 
      Supported formats       Autodetected by extension
      -----------------       -------------------------
@@ -2029,8 +2036,23 @@
     within it is committed.
 
     A selected-file commit may fail in some cases where the committed
-    tree would be invalid, such as trying to commit a file in a
-    newly-added directory that is not itself committed.
+    tree would be invalid. Consider::
+
+      bzr init foo
+      mkdir foo/bar
+      bzr add foo/bar
+      bzr commit foo -m "committing foo"
+      bzr mv foo/bar foo/baz
+      mkdir foo/bar
+      bzr add foo/bar
+      bzr commit foo/bar -m "committing bar but not baz"
+
+    In the example above, the last commit will fail by design. This gives
+    the user the opportunity to decide whether they want to commit the
+    rename at the same time, separately first, or not at all. (As a general
+    rule, when in doubt, Bazaar has a policy of Doing the Safe Thing.)
+
+    Note: A selected-file commit after a merge is not yet supported.
     """
     # TODO: Run hooks on tree to-be-committed, and after commit.
 
@@ -2454,14 +2476,14 @@
 
     Examples:
 
-    To merge the latest revision from bzr.dev
-    bzr merge ../bzr.dev
+    To merge the latest revision from bzr.dev:
+        bzr merge ../bzr.dev
 
-    To merge changes up to and including revision 82 from bzr.dev
-    bzr merge -r 82 ../bzr.dev
+    To merge changes up to and including revision 82 from bzr.dev:
+        bzr merge -r 82 ../bzr.dev
 
     To merge the changes introduced by 82, without previous changes:
-    bzr merge -r 81..82 ../bzr.dev
+        bzr merge -r 81..82 ../bzr.dev
     
     merge refuses to run if there are any uncommitted changes, unless
     --force is given.
@@ -2633,6 +2655,7 @@
     pending merge, and it lets you specify particular files.
 
     Examples:
+
     $ bzr remerge --show-base
         Re-do the merge of all conflicted files, and show the base text in
         conflict regions, in addition to the usual THIS and OTHER texts.