From 78744677ce30b4d744c3bc96c5400188054a4163 Mon Sep 17 00:00:00 2001 From: Eli Zaretskii Date: Sat, 26 Dec 2015 17:09:25 +0200 Subject: [PATCH] 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 359b50321c7..cb43f767aa3 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 +@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 09b8c8824d1..a53c4540d03 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 8d72a365614..f05d45cabc1 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))) -- 2.39.2