Function: projectile-completing-read

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

Signature

(projectile-completing-read PROMPT CHOICES &key INITIAL-INPUT ACTION CALLER SORT-FUNCTION ANNOTATION-FUNCTION (CATEGORY 'project-file))

Documentation

Present a project tailored PROMPT with CHOICES.

Reads with completing-read, unless projectile-completion-system is a function, in which case that function is called with PROMPT and CHOICES.

INITIAL-INPUT is passed to completing-read. ACTION, when non-nil, is called on the selected candidate and its result returned. SORT-FUNCTION, when non-nil, is exposed as the completion metadata's display-sort-function and cycle-sort-function, so completion UIs that honor metadata present the candidates in that order.

ANNOTATION-FUNCTION, when non-nil, is exposed as the metadata's annotation-function, so UIs that honor metadata show a suffix next to each candidate. Use it when the candidate string alone doesn't identify what's being picked - a worktree's path doesn't say which branch it has checked out, for instance.

CATEGORY is the completion metadata category advertised to UIs like marginalia and embark so they annotate and act on the candidates appropriately; it defaults to project-file (the candidates are project files) and should be overridden when they are not - e.g. buffer for a buffer switch or file for a directory. A nil CATEGORY omits it.

CALLER is accepted for backward compatibility but no longer used.

Source Code

;; Defined in ~/.emacs.d/elpa/projectile-20260820.1509/projectile.el
(cl-defun projectile-completing-read (prompt choices &key initial-input action caller sort-function annotation-function (category 'project-file))
  "Present a project tailored PROMPT with CHOICES.

Reads with `completing-read', unless `projectile-completion-system' is a
function, in which case that function is called with PROMPT and CHOICES.

INITIAL-INPUT is passed to `completing-read'.  ACTION, when non-nil, is
called on the selected candidate and its result returned.  SORT-FUNCTION,
when non-nil, is exposed as the completion metadata's
`display-sort-function' and `cycle-sort-function', so completion UIs
that honor metadata present the candidates in that order.

ANNOTATION-FUNCTION, when non-nil, is exposed as the metadata's
`annotation-function', so UIs that honor metadata show a suffix next to
each candidate.  Use it when the candidate string alone doesn't identify
what's being picked - a worktree's path doesn't say which branch it has
checked out, for instance.

CATEGORY is the completion metadata category advertised to UIs like
marginalia and embark so they annotate and act on the candidates
appropriately; it defaults to `project-file' (the candidates are project
files) and should be overridden when they are not - e.g. `buffer' for a
buffer switch or `file' for a directory.  A nil CATEGORY omits it.

CALLER is accepted for backward compatibility but no longer used."
  (ignore caller)
  (let* ((prompt (projectile-prepend-project-name prompt))
         (res (if (functionp projectile-completion-system)
                  (funcall projectile-completion-system prompt choices)
                (completing-read
                 prompt
                 (lambda (string pred action)
                   ;; The completion category lets packages like marginalia
                   ;; and embark enhance how candidates are presented.
                   (if (eq action 'metadata)
                       `(metadata ,@(when category `((category . ,category)))
                                  ,@(when annotation-function
                                      `((annotation-function . ,annotation-function)))
                                  ,@(when sort-function
                                      `((display-sort-function . ,sort-function)
                                        (cycle-sort-function . ,sort-function))))
                     (complete-with-action action choices string pred)))
                 nil nil initial-input))))
    (if action (funcall action res) res)))