From 652bb5b80c57f9891f74c48f66e96fba29007f44 Mon Sep 17 00:00:00 2001
From: Tony Zorman <soliditsallgood@mailbox.org>
Date: Thu, 29 Dec 2022 12:23:56 +0100
Subject: [PATCH 2/2] ; Document use-package's :vc keyword

* doc/misc/use-package.texi (Installing packages):
(Install package):
Add documentation for :vc and link to the related chapter in the Emacs
manual.

* etc/NEWS: Mention :vc keyword
---
 doc/misc/use-package.texi | 45 +++++++++++++++++++++++++++++++++++++--
 etc/NEWS                  | 13 +++++++++++
 2 files changed, 56 insertions(+), 2 deletions(-)

diff --git a/doc/misc/use-package.texi b/doc/misc/use-package.texi
index 87105c4db0..d1d847c0e0 100644
--- a/doc/misc/use-package.texi
+++ b/doc/misc/use-package.texi
@@ -1554,8 +1554,11 @@ Installing packages
 (@pxref{Package Installation,,, emacs, GNU Emacs Manual}).  The
 @code{use-package} macro provides the @code{:ensure} and @code{:pin}
 keywords that interface with that package manager to automatically
-install packages.  This is particularly useful if you use your init
-file on more than one system.
+install packages.  The @code{:vc} keyword may be used to control how
+package sources are downloaded (e.g., from remote hosts)
+(@pxref{Fetching Package Sources,,, emacs, GNU Emacs Manual}).  This
+is particularly useful if you use your init file on more than one
+system.
 
 @menu
 * Install package::
@@ -1607,6 +1610,44 @@ Install package
 You can override the above setting for a single package by adding
 @w{@code{:ensure nil}} to its declaration.
 
+@findex :vc
+The @code{:vc} keyword can be used to control how packages are
+downloaded and/or installed.  It accepts the same arguments as
+@code{package-vc-selected-packages} (@pxref{Specifying Package
+Sources,,, emacs, GNU Emacs Manual}), except that a name need not
+explicitly be given: it is inferred from the declaration.  The
+accepted property list is augmented by a @code{:rev} keyword, which
+has the same shape as the @code{REV} argument to
+@code{package-vc-install}.  Notably -- even when not specified --
+@code{:rev} defaults to checking out the last release of the package.
+You can use @code{:rev :head} to check out the latest commit.
+
+For example,
+
+@lisp
+@group
+(use-package foo
+  :vc (:url "https://bar.com/foo" :rev :head))
+@end group
+@end lisp
+
+would try -- by invoking @code{package-vc-install} -- to install the
+latest commit of the package @code{foo} from the specified remote.
+
+This can also be used for local packages, by combining it with the
+@code{:load-path} (@pxref{Load path}) keyword:
+
+@lisp
+@group
+(use-package foo
+  :vc t
+  :load-path "/path/to/foo/)
+@end group
+@end lisp
+
+The above dispatches to @code{package-vc-install-from-checkout}
+(@pxref{Fetching Package Sources,,, emacs, GNU Emacs Manual}).
+
 @node Pinning packages
 @section Pinning packages using @code{:pin}
 @cindex installing package from specific archive
diff --git a/etc/NEWS b/etc/NEWS
index b121002b24..c63bd42fc8 100644
--- a/etc/NEWS
+++ b/etc/NEWS
@@ -276,6 +276,19 @@ distracting and easily confused with actual code, or a significant
 early aid that relieves you from moving the buffer or reaching for the
 mouse to consult an error message.
 
+** use-package
+
++++
+*** New ':vc' keyword.
+This keyword enables the user to control how packages are fetched by
+utilising 'package-vc.el'.  By default, it relays its arguments to
+'package-vc-install', but -- when combined with the ':load-path'
+keyword -- it can also call upon 'package-vc-install-from-checkout'
+instead.  If no revision is given via the ':rev' argument, use-package
+falls back to the last release (via 'package-vc-install's
+':last-release' argument).  To check out the last commit, use ':rev
+:head'.
+
 
 * New Modes and Packages in Emacs 30.1
 
-- 
2.40.0