[Emacs-diffs] emacs-25 7874467: Improve documentation of 'vc-push'

[Eli Zaretskii]

branch: emacs-25
commit 78744677ce30b4d744c3bc96c5400188054a4163
Author: Eli Zaretskii <address@hidden>
Commit: Eli Zaretskii <address@hidden>

    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.
---
 doc/emacs/maintaining.texi |   59 +++++++++++++++++++++++++------------------
 etc/NEWS                   |    1 +
 lisp/vc/vc.el              |   10 +++++--
 3 files changed, 42 insertions(+), 28 deletions(-)

diff --git a/doc/emacs/maintaining.texi b/doc/emacs/maintaining.texi
index 359b503..cb43f76 100644
--- 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
address@hidden 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.
-
address@hidden 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
 
address@hidden C-x v P
address@hidden 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}.
+
address@hidden 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
address@hidden 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.
 
address@hidden C-x v P
address@hidden 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 09b8c88..a53c454 100644
--- 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 8d72a36..f05d45c 100644
--- 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)))