Function: package-vc-install

package-vc-install is an autoloaded, interactive and byte-compiled function defined in package-vc.el.gz.

Signature

(package-vc-install PACKAGE &optional REV BACKEND)

Documentation

Fetch a PACKAGE and set it up for using with Emacs.

If PACKAGE is a string containing an URL, download the package from the repository at that URL; the function will try to guess the name of the package from the URL. This can be overridden by passing the optional argument NAME. If PACKAGE is a cons-cell, it should have the form (NAME . SPEC), where NAME is a symbol indicating the package name and SPEC is a plist as described in package-vc-selected-packages. Otherwise PACKAGE should be a symbol whose name is the package name, and the URL for the package will be taken from the package's metadata.

By default, this function installs the last revision of the package available from its repository. If REV is a string, it describes the revision to install, as interpreted by the VC backend. The special value :last-release (interactively, the prefix argument), will use the commit of the latest release, if it exists. The last release is the latest revision which changed the "Version:" header of the package's main Lisp file.

Optional argument BACKEND specifies the VC backend to use for cloning the package's repository; this is only possible if NAME-OR-URL is a URL, a string. If BACKEND is omitted or nil, the function uses package-vc-heuristic-alist to guess the backend. Note that by default, a VC package will be prioritized over a regular package, but it will not remove a VC package.

View in manual

Probably introduced at or before Emacs version 29.1.

Key Bindings

Source Code

;; Defined in /usr/src/emacs/lisp/emacs-lisp/package-vc.el.gz
;;;###autoload
(defun package-vc-install (package &optional rev backend name)
  "Fetch a PACKAGE and set it up for using with Emacs.

If PACKAGE is a string containing an URL, download the package
from the repository at that URL; the function will try to guess
the name of the package from the URL.  This can be overridden by
passing the optional argument NAME.  If PACKAGE is a cons-cell,
it should have the form (NAME . SPEC), where NAME is a symbol
indicating the package name and SPEC is a plist as described in
`package-vc-selected-packages'.  Otherwise PACKAGE should be a
symbol whose name is the package name, and the URL for the
package will be taken from the package's metadata.

By default, this function installs the last revision of the
package available from its repository.  If REV is a string, it
describes the revision to install, as interpreted by the VC
backend.  The special value `:last-release' (interactively, the
prefix argument), will use the commit of the latest release, if
it exists.  The last release is the latest revision which changed
the \"Version:\" header of the package's main Lisp file.

Optional argument BACKEND specifies the VC backend to use for cloning
the package's repository; this is only possible if NAME-OR-URL is a URL,
a string.  If BACKEND is omitted or nil, the function
uses `package-vc-heuristic-alist' to guess the backend.
Note that by default, a VC package will be prioritized over a
regular package, but it will not remove a VC package.

\(fn PACKAGE &optional REV BACKEND)"
  (interactive
   (progn
     ;; Initialize the package system to get the list of package
     ;; symbols for completion.
     (package-vc--archives-initialize)
     (let* ((name-or-url (package-vc--read-package-name
                          "Fetch and install package: " t))
            (name (file-name-base (directory-file-name name-or-url))))
       (when (string-empty-p name)
         (user-error "Empty package name"))
       (list name-or-url
             (and current-prefix-arg :last-release)
             nil
             (intern (string-remove-prefix "emacs-" name))))))
  (package-vc--archives-initialize)
  (cond
   ((null package)
    (signal 'wrong-type-argument nil))
   ((consp package)
    (package-vc--unpack
     (package-desc-create :name (car package)
                          :kind 'vc)
     (cdr package)
     rev))
   ((and-let* (((stringp package))
               (backend (or backend (package-vc--guess-backend package))))
      (package-vc--unpack
       (package-desc-create
        :name (or name (intern (file-name-base package)))
        :kind 'vc)
       (list :vc-backend backend :url package)
       rev)))
   ((and-let* ((desc (assoc package package-archive-contents #'string=)))
      (package-vc--unpack
       (cadr desc)
       (or (package-vc--desc->spec (cadr desc))
           (and-let* ((extras (package-desc-extras (cadr desc)))
                      (url (alist-get :url extras))
                      (backend (package-vc--guess-backend url)))
             (list :vc-backend backend :url url))
           (user-error "Package `%s' has no VC data" package))
       rev)))
   ((user-error "Unknown package to fetch: %s" package))))