https://github.com/slotthe/vc-use-package
Primitive package-vc integration for use-package
https://github.com/slotthe/vc-use-package
emacs emacs-lisp use-package
Last synced: about 1 month ago
JSON representation
Primitive package-vc integration for use-package
- Host: GitHub
- URL: https://github.com/slotthe/vc-use-package
- Owner: slotThe
- License: gpl-3.0
- Created: 2022-12-22T11:26:20.000Z (over 2 years ago)
- Default Branch: master
- Last Pushed: 2024-11-26T05:33:47.000Z (6 months ago)
- Last Synced: 2025-03-26T06:51:07.501Z (about 2 months ago)
- Topics: emacs, emacs-lisp, use-package
- Language: Emacs Lisp
- Homepage:
- Size: 61.5 KB
- Stars: 53
- Watchers: 4
- Forks: 6
- Open Issues: 0
-
Metadata Files:
- Readme: README.md
- License: LICENSE
Awesome Lists containing this project
README
# `vc-use-package`
Primitive integration of `package-vc.el` into [use-package].
> [!NOTE]
> As of 2023-05-16, `vc-use-package` has been
> [merged](https://git.savannah.gnu.org/cgit/emacs.git/commit/?id=2ce279680bf9c1964e98e2aa48a03d6675c386fe)
> into Emacs `master`!
> Thus, if you are using a recent enough version of Emacs 30+,
> you don't need to install this package and can instead use `use-package`s own `:vc` keyword.
>
> **Note that the keyword syntax differs in the core differs from that used in this package!**
> Instead of a MELPA-style `:vc (:fetcher github :repo oantolin/math-delimiters)`, the built-in keyword
> uses ELPA-style `:vc (:url "https://github.com/oantolin/math-delimiters")` package specifications.
> Please refer to the use-package and the Emacs manual for more details.
> If you want to use the ELPA-style syntax with `vc-use-package`,
> see [here](#directly-using-package-vcels-interface).
## Installation
Install with `package-vc-install`:
``` emacs-lisp
(unless (package-installed-p 'vc-use-package)
(package-vc-install "https://github.com/slotThe/vc-use-package"))
(require 'vc-use-package)
```
## Usage
This package adds a new `:vc` keywords to `use-package` declarations,
with which you can install packages. For example:
``` emacs-lisp
(use-package math-delimiters
:vc (:fetcher github :repo oantolin/math-delimiters))
```
The argument to `:vc` is a plist with the following keywords: `:fetcher
:repo :rev :backend`.
For a list of supported fetchers, see `vc-use-package-fetchers`.
Additionally, `:fetcher` may also be a URL, in which case it is followed
verbatim. The `:rev` and `:backend` keywords are given to
`vc-package-install` as-is. The `:fetcher` and `:repo` arguments may
either be strings, or symbols (as above).
### Directly using `package-vc.el`s interface
By giving `:vc` a cons-pair of a package name, as well as a relevant
plist, one can also directly use the interface specified by
`package-vc-selected-packages`. For example, this can be used to check
out specific branches, or to exclusively use URLs for fetching packages:
``` emacs-lisp
(use-package modus-themes
:vc (modus-themes :url "https://gitlab.com/protesilaos/modus-themes"
:branch "main"))
```
Another example would be to correctly install a package with an
"extension" directory:
``` emacs-lisp
(use-package dirvish
:vc (dirvish :url "https://github.com/alexluigit/dirvish"
:lisp-dir "extensions/"))
```
### In combination with `use-package-always-ensure`
When using `use-package-always-ensure`, make sure that the variable is
set before `vc-use-package` is loaded; e.g.,
``` emacs-lisp
(setopt use-package-always-ensure t)
(require 'vc-use-package)
```
Everything should work out of the box in this case.
The function `vc-use-package-activate-advice` may also be called manually to install the necessary advice.
In the other direction, `vc-use-package-deactivate-advice` exists to remove this behaviour.
## Further customisations
### Only doing shallow clones ([#20](https://github.com/slotThe/vc-use-package/issues/20))
This can be done by monkey-patching the relevant `vc-«backend»-clone` functions, depending on which backend is used.
For example,
``` emacs-lisp
(defun my/vc-git-clone (fn remote directory rev)
(if (or (not (string-match-p "elpa" directory))
(null rev))
(funcall fn remote directory rev)
(cond
((ignore-errors
;; First try if rev is a branch/tag name
;; https://stackoverflow.com/a/48748567/2163429
(vc-git--out-ok "clone" "--depth" "1" "--single-branch" "--branch" rev remote directory)))
((vc-git--out-ok "clone" "--single-branch" remote directory)
(let ((default-directory directory))
(vc-git--out-ok "checkout" rev))))
directory))
(advice-add #'vc-git-clone :around #'my/vc-git-clone)
```
[use-package]: https://github.com/jwiegley/use-package/