From f4bc4ac5448eda45c9de938dceb280b9854c1b1b 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 | 41 +++++++++++++++++++++++++++++++++++++--
 etc/NEWS                  | 12 ++++++++++++
 2 files changed, 51 insertions(+), 2 deletions(-)

diff --git a/doc/misc/use-package.texi b/doc/misc/use-package.texi
index 87105c4db0..6316af23ca 100644
--- a/doc/misc/use-package.texi
+++ b/doc/misc/use-package.texi
@@ -1554,8 +1554,10 @@ 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.  Further, the @code{:vc} keyword may be used to
+control how package sources are fetched (@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 +1609,41 @@ 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 fetched.
+It accepts the same arguments as @code{package-vc-selected-packages},
+except that a name need not explicitly given: it is inferred from the
+declaration.  Further, 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}.
+
 @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..40cf44dd30 100644
--- a/etc/NEWS
+++ b/etc/NEWS
@@ -276,6 +276,18 @@ 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.  Further, if no revision is given via the ':rev' argument, we
+fall 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