Improve documentation of 'vc-push'

* doc/emacs/maintaining.texi (Pulling / Pushing): Expand and
improve the documentation of 'vc-push'.

* lisp/vc/vc.el (vc-pull, vc-push): Doc fix.

diff --git a/doc/emacs/maintaining.texi b/doc/emacs/maintaining.texi
index 359b50321c7bc9b097cae6f7b1f04b976a540783..cb43f767aa31d849b6939bb43311afcb5fa2c537 100644 (file)
--- a/doc/emacs/maintaining.texi
+++ b/doc/emacs/maintaining.texi
@@ -1364,19 +1364,43 @@ commit will be committed to that specific branch.
 @subsubsection Pulling/Pushing Changes into/from a Branch
 
 @table @kbd
+@item C-x v P
+On a decentralized version control system, update another location
+with changes from the current branch (a.k.a. ``push'' changes).  This
+concept does not exist for centralized version control systems
+
 @item C-x v +
 On a decentralized version control system, update the current branch
 by ``pulling in'' changes from another location.
 
 On a centralized version control system, update the current VC
 fileset.
-
-@item C-x v P
-On a decentralized version control system, ``push'' changes from the
-current branch to another location.  This concept does not exist
-for centralized version control systems.
 @end table
 
+@kindex C-x v P
+@findex vc-push
+On a decentralized version control system, the command @kbd{C-x v P}
+(@code{vc-push}) updates another location with changes from the
+current branch.  With a prefix argument, it prompts for the exact
+version control command to run, which lets you specify where to push
+changes; the default is @command{bzr push} with Bazaar, @command{git
+push} with Git, and @command{hg push} with Mercurial.  The default
+commands always push to a default location determined by the version
+control system from your branch configuration.
+
+Prior to pushing, you can use @kbd{C-x v O} (@code{vc-log-outgoing})
+to view a log buffer of the changes to be sent.  @xref{VC Change Log}.
+
+@cindex bound branch (Bazaar VCS)
+This command is currently supported only by Bazaar, Git, and Mercurial.
+The concept of ``pushing'' does not exist for centralized version
+control systems, where this operation is a part of committing a
+changeset, so invoking this command on a centralized VCS signals an
+error.  This command also signals an error when attempted in a Bazaar
+@dfn{bound branch}, where committing a changeset automatically pushes
+the changes to the remote repository to which the local branch is
+bound.
+
 @kindex C-x v +
 @findex vc-pull
   On a decentralized version control system, the command @kbd{C-x v +}
@@ -1388,12 +1412,12 @@ Otherwise, it pulls from a default location determined by the version
 control system.
 
   Amongst decentralized version control systems, @kbd{C-x v +} is
-currently supported only by Bazaar, Git, and Mercurial.  On Bazaar, it
-calls @command{bzr pull} for ordinary branches (to pull from a master
-branch into a mirroring branch), and @command{bzr update} for a bound
-branch (to pull from a central repository).  On Git, it calls
+currently supported only by Bazaar, Git, and Mercurial.  With Bazaar,
+it calls @command{bzr pull} for ordinary branches (to pull from a
+master branch into a mirroring branch), and @command{bzr update} for a
+bound branch (to pull from a central repository).  With Git, it calls
 @command{git pull} to fetch changes from a remote repository and merge
-it into the current branch.  On Mercurial, it calls @command{hg pull
+it into the current branch.  With Mercurial, it calls @command{hg pull
 -u} to fetch changesets from the default remote repository and update
 the working directory.
 
@@ -1404,21 +1428,6 @@ Log}.
   On a centralized version control system like CVS, @kbd{C-x v +}
 updates the current VC fileset from the repository.
 
-@kindex C-x v P
-@findex vc-push
-  On a decentralized version control system, the command @kbd{C-x v P}
-(@code{vc-push}) sends changes from your current branch to another location.
-With a prefix argument, the command prompts for the exact
-version control command to use, which lets you specify where to push
-changes.  Otherwise, it pushes to a default location determined
-by the version control system.
-
-  Prior to pushing, you can use @kbd{C-x v O} (@code{vc-log-outgoing})
-to view a log buffer of the changes to be sent.  @xref{VC Change Log}.
-
-This command is currently supported only by Bazaar, Git, and Mercurial.
-It signals an error for centralized version control systems.
-
 @node Merging
 @subsubsection Merging Branches
 @cindex merging changes

diff --git a/etc/NEWS b/etc/NEWS
index 09b8c8824d109ff9ae2a899eef377f23b977d697..a53c4540d03ce97c6476bb6219a183d7687c982e 100644 (file)
--- a/etc/NEWS
+++ b/etc/NEWS
@@ -812,6 +812,7 @@ comments.
 
 ** VC and related modes
 
++++
 *** Basic push support, via `vc-push', bound to `C-x v P'.
 Implemented for Bzr, Git, Hg.  As part of this change, the pre-existing
 (undocumented) command vc-hg-push now behaves slightly differently.

diff --git a/lisp/vc/vc.el b/lisp/vc/vc.el
index 8d72a3656148df498d0928daba4ba6c816294d05..f05d45cabc167a8991995ece31f4126a6505078c 100644 (file)
--- a/lisp/vc/vc.el
+++ b/lisp/vc/vc.el
@@ -2467,7 +2467,8 @@ to the working revision (except for keyword expansion)."
 You must be visiting a version controlled file, or in a `vc-dir' buffer.
 On a distributed version control system, this runs a \"pull\"
 operation to update the current branch, prompting for an argument
-list if required.  Optional prefix ARG forces a prompt.
+list if required.  Optional prefix ARG forces a prompt for the VCS
+command to run.
 
 On a non-distributed version control system, update the current
 fileset to the tip revisions.  For each unchanged and unlocked
@@ -2511,8 +2512,11 @@ tip revision are merged into the working file."
 You must be visiting a version controlled file, or in a `vc-dir' buffer.
 On a distributed version control system, this runs a \"push\"
 operation on the current branch, prompting for the precise command
-if required.  Optional prefix ARG non-nil forces a prompt.
-On a non-distributed version control system, this signals an error."
+if required.  Optional prefix ARG non-nil forces a prompt for the
+VCS command to run.
+
+On a non-distributed version control system, this signals an error.
+It also signals an error in a Bazaar bound branch."
   (interactive "P")
   (let* ((vc-fileset (vc-deduce-fileset t))
         (backend (car vc-fileset)))