:ensure's default and option subtilties undocumented

[legends2k]

There're 4 possible ways of using :ensure

;; 1
(use-package org
  :ensure t
)

;; 2
(use-package org
  :ensure nil
)

;; 3
(use-package org
)

;; 4
(use-package org
  :ensure org-plus-contrib
)

I understand that t would install the package if absent, while nil would load if present or skip. However, I don't see what the default (i.e. omission of ensure) would choose. The documentation is unclear on this. Also what happens to (4), t or nil for org or org-plus-contrib?

[waymondo]

Regarding the default behavior (#3), it would be the same as setting :ensure nil. Unless you configure use-package-always-ensure to t: https://github.com/jwiegley/use-package/blob/master/use-package-ensure.el#L47-L51

[conao3]

agree with @waymondo. there're any concerns?

[legends2k]

The documentation is unclear on this. Also what happens to (4), t or nil for org or org-plus-contrib?

The main concern is improving documentation; making sure all flags/variants/args are given some explanation.

[skangas]

This is the text in the current use-package manual that is due for release with the version of use-package that will be shipped with Emacs 29:

File: use-package.info,  Node: Install package,  Next: Pinning packages,  Up: Installing packages

5.1 Installing package
======================

The ‘:ensure’ keyword makes use-package ask the Emacs package manager
to install a package if it is not already present on your system.

   For example:

     (use-package magit
       :ensure t)

   If you need to install a different package from the one named by
‘use-package’, you can use a symbol:

     (use-package tex
       :ensure auctex)

   You can customize the user option ‘use-package-always-ensure’ to
non-‘nil’ if you want this behavior to be global for all packages.

     (require 'use-package-ensure)
     (setq use-package-always-ensure t)

You can override the above setting for a single package by adding
‘:ensure nil’ to its declaration.

Is that sufficiently clear? If not, what's missing? Thanks.

[legends2k]

This seems clear, thank you.

[skangas]

This seems clear, thank you.

Thanks for verifying that. I'm happy that you find the above text clear.