Function: magit-completing-read

magit-completing-read is a byte-compiled function defined in magit-base.el.

Signature

(magit-completing-read PROMPT COLLECTION &optional PREDICATE REQUIRE-MATCH INITIAL-INPUT HIST DEF FALLBACK)

Documentation

Read a choice in the minibuffer, or use the default choice.

This is the function that Magit commands use when they need the user to select a single thing to act on. The arguments have the same meaning as for completing-read, except for FALLBACK, which is unique to this function and is described below.

Instead of asking the user to choose from a list of possible candidates, this function may instead just return the default specified by DEF, with or without requiring user confirmation. Whether that is the case depends on PROMPT, this-command and magit-dwim-selection. See the documentation of the latter for more information.

If it does use the default without the user even having to confirm that, then magit-completing-read--silent-default is set to t, otherwise nil.

If it does read a value in the minibuffer, then this function acts similarly to completing-read, except for the following:

- COLLECTION must be a list of choices. A function is not
  supported.

- If REQUIRE-MATCH is nil and the user exits without a choice,
  then nil is returned instead of an empty string.

- If REQUIRE-MATCH is any, then do not require a match but
  do require non-empty input (or non-nil DEFAULT, since that
  is substituted for empty input).

- If REQUIRE-MATCH is non-nil and the user exits without a
  choice, user-error is raised.

- FALLBACK specifies a secondary default that is only used if
  the primary default DEF is nil. The secondary default is not
  subject to magit-dwim-selection — if DEF is nil but FALLBACK
  is not, then this function always asks the user to choose a
  candidate, just as if both defaults were nil.

- format-prompt is called on PROMPT and DEF (or FALLBACK if
  DEF is nil). This appends ": " to the prompt and may also
  add the default to the prompt, using the format specified by
  minibuffer-default-prompt-format and depending on
  magit-completing-read-default-prompt-predicate.

Source Code

;; Defined in ~/.emacs.d/elpa/magit-20260411.1452/magit-base.el
(defun magit-completing-read ( prompt collection &optional
                               predicate require-match initial-input
                               hist def fallback)
  "Read a choice in the minibuffer, or use the default choice.

This is the function that Magit commands use when they need the
user to select a single thing to act on.  The arguments have the
same meaning as for `completing-read', except for FALLBACK, which
is unique to this function and is described below.

Instead of asking the user to choose from a list of possible
candidates, this function may instead just return the default
specified by DEF, with or without requiring user confirmation.
Whether that is the case depends on PROMPT, `this-command' and
`magit-dwim-selection'.  See the documentation of the latter for
more information.

If it does use the default without the user even having to
confirm that, then `magit-completing-read--silent-default' is set
to t, otherwise nil.

If it does read a value in the minibuffer, then this function
acts similarly to `completing-read', except for the following:

- COLLECTION must be a list of choices.  A function is not
  supported.

- If REQUIRE-MATCH is nil and the user exits without a choice,
  then nil is returned instead of an empty string.

- If REQUIRE-MATCH is `any', then do not require a match but
  do require non-empty input (or non-nil DEFAULT, since that
  is substituted for empty input).

- If REQUIRE-MATCH is non-nil and the user exits without a
  choice, `user-error' is raised.

- FALLBACK specifies a secondary default that is only used if
  the primary default DEF is nil.  The secondary default is not
  subject to `magit-dwim-selection' — if DEF is nil but FALLBACK
  is not, then this function always asks the user to choose a
  candidate, just as if both defaults were nil.

- `format-prompt' is called on PROMPT and DEF (or FALLBACK if
  DEF is nil).  This appends \": \" to the prompt and may also
  add the default to the prompt, using the format specified by
  `minibuffer-default-prompt-format' and depending on
  `magit-completing-read-default-prompt-predicate'."
  (setq magit-completing-read--silent-default nil)
  (if-let ((_ def)
           (dwim (seq-some (pcase-lambda (`(,cmd ,re ,dwim))
                             (and (eq cmd this-command)
                                  (or (not re)
                                      (string-match-p re prompt))
                                  dwim))
                           magit-dwim-selection)))
      (if (eq dwim 'ask)
          (if (y-or-n-p (format "%s %s? " prompt def))
              def
            (user-error "Abort"))
        (setq magit-completing-read--silent-default t)
        def)
    (unless def
      (setq def fallback))
    (when (and def
               (not (functionp collection))
               (not (member def collection)))
      (setq collection (cons def collection)))
    (let ((command this-command)
          (reply (funcall magit-completing-read-function
                          (magit--format-prompt prompt def)
                          collection predicate
                          (if (eq require-match 'any) nil require-match)
                          initial-input hist def)))
      (setq this-command command)
      ;; Note: Avoid `string=' to support `helm-comp-read-use-marked'.
      (if (equal reply "")
          (if (and require-match
                   (not (and (listp collection)
                             (member "" collection))))
              (user-error "Nothing selected")
            nil)
        reply))))