### Minimal Setup with Default Completion System for emacs -Q

Source: https://github.com/minad/consult/blob/main/README.org

This snippet provides the minimal Emacs Lisp configuration for using Consult with the default completion system when starting Emacs with '-Q'. It initializes packages, requires Consult, and sets completion styles.

```emacs-lisp
(package-initialize)
(require 'consult)
(setq completion-styles '(substring basic))
```

--------------------------------

### Minimal Setup with Vertico for emacs -Q

Source: https://github.com/minad/consult/blob/main/README.org

This snippet shows the minimal Emacs Lisp configuration required to use Consult with Vertico when starting Emacs with '-Q'. It initializes packages, requires Consult and Vertico, enables vertico-mode, and sets completion styles.

```emacs-lisp
(package-initialize)
(require 'consult)
(require 'vertico)
(vertico-mode)
(setq completion-styles '(substring basic))
```

--------------------------------

### Consult find command examples

Source: https://github.com/minad/consult/blob/main/_autodocs/api-reference/consult-search.md

Initiate a file search using consult-find. The first example performs a general search, while the second searches for files matching 'main.c'.

```elisp
(consult-find)
```

```elisp
(consult-find nil "main\.c")
```

--------------------------------

### Consult Narrowing Example

Source: https://github.com/minad/consult/blob/main/_autodocs/api-reference/consult-modes-commands.md

Illustrates how to use the configured narrowing key to filter completion results. For example, typing '<b' in consult-buffer narrows to buffers.

```elisp
;; With consult-narrow-key set to "<":
;; In consult-buffer: type "<b" to narrow to buffers
;;                    type "<f" to narrow to files
;;                    type "<<" to widen back
```

--------------------------------

### Setup for Vertico Completion UI

Source: https://github.com/minad/consult/blob/main/_autodocs/README.md

Configures Consult with keybindings for buffer, grep, and line searches, and sets custom narrow and preview keys.

```elisp
(use-package consult
  :bind (("C-c b" . consult-buffer)
         ("C-c s" . consult-grep)
         ("C-c l" . consult-line)
         ("M-s g" . consult-grep)
         ("M-s l" . consult-line))
  :config
  (setq consult-narrow-key "<")
  (setq consult-preview-key 'any))
```

--------------------------------

### Example: Open or Create Bookmark

Source: https://github.com/minad/consult/blob/main/_autodocs/api-reference/consult-navigation.md

Demonstrates how to use `consult-bookmark` to open an existing bookmark or create a new one if it doesn't exist. Supports preview and narrowing.

```elisp
(consult-bookmark "my-project-root")
;; If the bookmark doesn't exist, creates it
;; If it does, jumps to it with preview
```

--------------------------------

### Configure Consult Buffer Sources

Source: https://github.com/minad/consult/wiki/Home.org

Example of how to set `consult-buffer-sources` to include the custom mixed file source.

```emacs-lisp
(setq consult-buffer-sources
        '( consult--source-hidden-buffer
           consult--source-buffer
           consult--source-mixed-file
           consult--source-bookmark
           consult--source-project-buffer
           consult--source-project-file))
```

--------------------------------

### Consult locate command example

Source: https://github.com/minad/consult/blob/main/_autodocs/api-reference/consult-search.md

Initiate a file search using the consult-locate command, which leverages the system's locate database for fast lookups.

```elisp
(consult-locate "config")
```

--------------------------------

### Configure consult-line to start from top

Source: https://github.com/minad/consult/blob/main/_autodocs/api-reference/consult-search.md

Set consult-line to always start searching from the top of the buffer, overriding the default behavior of starting from the current line.

```elisp
(setq consult-line-start-from-top t)
```

--------------------------------

### Consult fd command example

Source: https://github.com/minad/consult/blob/main/_autodocs/api-reference/consult-search.md

Initiate a file search using the consult-fd command, which utilizes the fd utility for faster searching.

```elisp
(consult-fd)
```

--------------------------------

### consult-grep search with initial input

Source: https://github.com/minad/consult/blob/main/_autodocs/api-reference/consult-search.md

Starts a grep search with a predefined initial string, such as 'TODO'. This helps pre-populate the search query.

```elisp
(consult-grep nil "TODO")
```

--------------------------------

### Use-package Configuration for Consult

Source: https://github.com/minad/consult/blob/main/README.org

Example configuration for the Consult package using the use-package macro. It sets up various keybindings for frequently used Consult commands.

```emacs-lisp
;; Example configuration for Consult
(use-package consult
  ;; Replace bindings. Lazily loaded by `use-package'.
  :bind (;; C-c bindings in `mode-specific-map'
         ("C-c M-x" . consult-mode-command)
         ("C-c h" . consult-history)
         ("C-c k" . consult-kmacro)
         ("C-c m" . consult-man)
         ("C-c i" . consult-info)
         ([remap Info-search] . consult-info)
         ;; C-x bindings in `ctl-x-map'
         ("C-x M-:" . consult-complex-command)     ;; orig. repeat-complex-command
         ("C-x b" . consult-buffer)                ;; orig. switch-to-buffer
         ("C-x 4 b" . consult-buffer-other-window) ;; orig. switch-to-buffer-other-window
         ("C-x 5 b" . consult-buffer-other-frame)  ;; orig. switch-to-buffer-other-frame
         ("C-x t b" . consult-buffer-other-tab)    ;; orig. switch-to-buffer-other-tab
         ("C-x r b" . consult-bookmark)            ;; orig. bookmark-jump
         ("C-x p b" . consult-project-buffer)      ;; orig. project-switch-to-buffer
         ;; Custom M-# bindings for fast register access
         ("M-#" . consult-register-load)
         ("M-'" . consult-register-store)          ;; orig. abbrev-prefix-mark (unrelated)
         ("C-M-#" . consult-register)
         ;; Other custom bindings

```

--------------------------------

### Completion Category Metadata Example

Source: https://github.com/minad/consult/blob/main/_autodocs/types.md

An example of metadata used for completion categories, specifying a category name and a custom display sort function.

```elisp
(quote
 (metadata (category . consult-grep)
           (display-sort-function . consult--prefix-group)))
```

--------------------------------

### Bind Consult Narrow Help

Source: https://github.com/minad/consult/blob/main/_autodocs/api-reference/consult-modes-commands.md

Example of binding the consult-narrow-help function to a key, such as '?' in the minibuffer, to display narrowing options during completion.

```elisp
;; Bind to show help during completion
(define-key minibuffer-local-map (kbd "?") #'consult-narrow-help)

;; Or call directly to see available narrowing options
(consult-narrow-help)
```

--------------------------------

### Example: Load a Register

Source: https://github.com/minad/consult/blob/main/_autodocs/api-reference/consult-navigation.md

Demonstrates loading a specific register by its character name. The action taken depends on the register's content type (window configuration, text, or marker).

```elisp
(consult-register-load ?a)  ; load register 'a'
```

--------------------------------

### Example: Store Content in Register

Source: https://github.com/minad/consult/blob/main/_autodocs/api-reference/consult-navigation.md

Shows how to store content into a register. Behavior varies based on prefix arguments and whether a region is active, supporting storage of point position, region content, numbers, or window configurations.

```elisp
(consult-register-store 1)
;; With region selected and C-u, stores and deletes region
;; With point, stores position marker

(let ((current-prefix-arg '(4)))
  (call-interactively #'consult-register-store))
```

```elisp
;; Stores and deletes active region
;; With point, stores position marker
```

--------------------------------

### Consult line command examples

Source: https://github.com/minad/consult/blob/main/_autodocs/api-reference/consult-search.md

Perform a line search within the current buffer using consult-line. The first example performs a general search, while the second searches for lines containing 'TODO'.

```elisp
(consult-line)
```

```elisp
(consult-line "TODO")
```

--------------------------------

### Configure Multiple Preview Delays for Consult Theme

Source: https://github.com/minad/consult/blob/main/README.org

Configure `consult-theme` to use different preview delay strategies based on the key pressed. This example sets immediate preview for 'M-.', a 0.5s delay for up/down arrows, and a 1s delay for any other key.

```emacs-lisp
;; Preview immediately on M-., on up/down after 0.5s, on any other key after 1s
(consult-customize consult-theme
                   :preview-key
                   '("M-"
                     :debounce 0.5 "<up>" "<down>"
                     :debounce 1 any))
```

--------------------------------

### Configure consult-find arguments

Source: https://github.com/minad/consult/blob/main/_autodocs/api-reference/consult-search.md

Set the default arguments for the consult-find command. This example excludes hidden files and directories.

```elisp
(setq consult-find-args "find . -not ( -path '*/.[A-Za-z]*' -prune )")
```

--------------------------------

### Example Category-Specific Minibuffer Keybinding

Source: https://github.com/minad/consult/wiki/Home.org

Demonstrates using `define-minibuffer-key` to bind C-s to different commands based on the completion category, such as navigating history or finding files.

```emacs-lisp
(define-minibuffer-key "\C-s"
    'consult-location #'previous-history-element
    'file #'consult-find-for-minibuffer)

```

--------------------------------

### Configure consult-preview-excluded-files

Source: https://github.com/minad/consult/blob/main/_autodocs/configuration.md

Provide a list of regular expressions matching files that should be excluded from preview. This example excludes remote, encrypted, and archive files.

```elisp
(setq consult-preview-excluded-files
      '("\`/[^/|:]+:`  ; remote files
        \.gpg\'")     ; encrypted files
        "\.zip\'\))   ; archives
```

--------------------------------

### Creating Simple Commands with consult--read (Other Text Properties)

Source: https://github.com/minad/consult/blob/main/README.org

This example demonstrates adding custom text properties, such as face attributes, to completion candidates using consult--read. It formats the display string and associates a value with each candidate.

```emacs-lisp
(consult--read
 (mapcar (lambda (value)
           (propertize
            (format "%s %s" 
                    (propertize "Option" 'face 'font-lock-comment-face)
                    value))
            'consult--candidate value))
         '("A" "B" "C"))
 :prompt "Select: "
 :sort nil
 :lookup #'consult--lookup-candidate)
```

--------------------------------

### Customize Consult Preview Key Bindings

Source: https://github.com/minad/consult/blob/main/README.org

Configure the preview key behavior for various Consult commands. This example sets a delayed preview for several commands.

```emacs-lisp
(consult-customize
 consult-ripgrep consult-git-grep consult-grep consult-man
 consult-bookmark consult-recent-file consult-xref
 consult-source-bookmark consult-source-file-register
 consult-source-recent-file consult-source-project-recent-file
 :preview-key '(:debounce 0.4 any)) ;; Option 1: Delay preview
 ;; :preview-key "M-."              ;; Option 2: Manual preview
```

--------------------------------

### Configure consult-locate arguments

Source: https://github.com/minad/consult/blob/main/_autodocs/api-reference/consult-search.md

Set the default arguments for the consult-locate command. This example configures locate to ignore case during searches.

```elisp
(setq consult-locate-args "locate --ignore-case")
```

--------------------------------

### Configure consult-find Arguments

Source: https://github.com/minad/consult/blob/main/_autodocs/configuration.md

Set custom command-line arguments for the `consult-find` command. This example excludes hidden files.

```elisp
(setq consult-find-args "find . -not ( -path \"./.[A-Za-z]*\" -prune )")
```

--------------------------------

### Configure Initial Narrowing Per Command

Source: https://github.com/minad/consult/wiki/Home.org

Sets up initial narrowing for specific Consult commands. This allows the completion UI to start with a pre-filtered set of results.

```elisp
;; Configure initial narrowing per command
(defvar consult-initial-narrow-config
    '((consult-buffer . ?b)))

;; Add initial narrowing hook
(defun consult-initial-narrow ()
  (when-let (key (alist-get this-command consult-initial-narrow-config))
    (setq unread-command-events (append unread-command-events (list key 32)))))
(add-hook 'minibuffer-setup-hook #'consult-initial-narrow)
```

--------------------------------

### Start Consult Line with Symbol at Point

Source: https://github.com/minad/consult/wiki/Home.org

Initiates a consult-line search using the symbol at the current cursor position as the initial input.

```elisp
(defun consult-line-symbol-at-point ()
    (interactive)
    (consult-line (thing-at-point 'symbol)))
```

--------------------------------

### Configure consult-man Arguments

Source: https://github.com/minad/consult/blob/main/_autodocs/configuration.md

Set custom command-line arguments for the `consult-man` command. This example uses `man -k` for keyword searching.

```elisp
(setq consult-man-args "man -k")
```

--------------------------------

### Example: Access Emacs Registers

Source: https://github.com/minad/consult/blob/main/_autodocs/api-reference/consult-navigation.md

Opens the interactive interface for Emacs registers. Allows selecting text registers, position markers, or window configurations for insertion or jumping.

```elisp
(consult-register)
;; Shows: text registers, position markers, window configs
;; Select to either insert text or jump to marker
```

--------------------------------

### Preselect Recent Tab with Vertico

Source: https://github.com/minad/consult/wiki/Home.org

Hooks into `minibuffer-setup-hook` to preselect the most recent tab when commands in `+consult--tab-index-commands` are invoked. It also adds advice to `vertico--setup` to refresh the Consult interface.

```emacs-lisp
(defvar +consult--tab-index-commands '(+tab-bar-dwim
                                       +consult-tab
                                       +consult-tab-close*)
  "List of commands that will trigger `+consult--tab-index-preselect' and `+consult--tab-index-refresh'")
```

```emacs-lisp
(defun +consult--tab-index-preselect ()
  "Preselect recent tab if `this-command' in `+consult--tab-index-commands'."
  (when (memq this-command +consult--tab-index-commands)
    (vertico--goto (or (tab-bar--tab-index-recent 1)
                       (tab-bar--current-tab-index)))))
```

```emacs-lisp
(add-hook 'minibuffer-setup-hook #'+consult--tab-index-preselect)
```

```emacs-lisp
(defun +consult--tab-index-refresh ()
  "Run `consult-vertico--refresh' if `this-command' in `+consult--tab-index-commands'."
  (when (memq this-command +consult--tab-index-commands)
    (consult--vertico-refresh)))
```

```emacs-lisp
(advice-add #'vertico--setup :after #'+consult--tab-index-refresh)
```

--------------------------------

### Configure Delayed Previews for Consult Theme

Source: https://github.com/minad/consult/blob/main/README.org

Customize the preview behavior for the `consult-theme` command to improve UI smoothness by delaying the preview. This example shows a 0.5s delay.

```emacs-lisp
;; Preview on any key press, but delay 0.5s
(consult-customize consult-theme :preview-key '(:debounce 0.5 any))
```

--------------------------------

### Consult line-multi command example

Source: https://github.com/minad/consult/blob/main/_autodocs/api-reference/consult-search.md

Search for lines containing 'TODO' across multiple buffers using consult-line-multi. This command is useful for finding specific content across different files.

```elisp
(consult-line-multi "TODO")
```

--------------------------------

### Consult Initialization and Configuration

Source: https://github.com/minad/consult/blob/main/README.org

This Emacs Lisp snippet demonstrates the `:init` and `:config` sections for Consult. It shows how to advise `register-preview` for better register display and configure `xref` to use Consult for showing locations and definitions.

```emacs-lisp
;; The :init configuration is always executed (Not lazy)
:init

;; Tweak the register preview for `consult-register-load',
;; `consult-register-store' and the built-in commands.  This improves the
;; register formatting, adds thin separator lines, register sorting and hides
;; the window mode line.
(advice-add #'register-preview :override #'consult-register-window)
(setq register-preview-delay 0.5)

;; Use Consult to select xref locations with preview
(setq xref-show-xrefs-function #'consult-xref
      xref-show-definitions-function #'consult-xref)

;; Configure other variables and modes in the :config section,
;; after lazily loading the package.
:config

;; Optionally configure preview. The default value
;; is 'any, such that any key triggers the preview.
;; (setq consult-preview-key 'any)
;; (setq consult-preview-key "M-.")
;; (setq consult-preview-key '("S-<down>" "S-<up>"))
;; For some commands and buffer sources it is useful to configure the
;; :preview-key on a per-command basis using the `consult-customize' macro.
(consult-customize
 consult-theme :preview-key '(:debounce 0.2 any)
 consult-ripgrep consult-git-grep consult-grep consult-man
 consult-bookmark consult-recent-file consult-xref
 consult-source-bookmark consult-source-file-register
 consult-source-recent-file consult-source-project-recent-file
 ;; :preview-key "M-"
 :preview-key '(:debounce 0.4 any))

;; Optionally configure the narrowing key.
;; Both < and C-+ work reasonably well.
(setq consult-narrow-key "<") ;; "C-+"

;; Optionally make narrowing help available in the minibuffer.
;; You may want to use `embark-prefix-help-command' or which-key instead.
;; (keymap-set consult-narrow-map (concat consult-narrow-key " ?") #'consult-narrow-help)
)
#+end_src
```

--------------------------------

### Switch Buffers with Preview

Source: https://github.com/minad/consult/blob/main/_autodocs/00-START-HERE.md

Opens the Consult interface to switch between buffers, displaying a live preview of the selected buffer.

```elisp
(consult-buffer)           ; switch with preview
```

--------------------------------

### Adjust Consult Async Input Debounce

Source: https://github.com/minad/consult/blob/main/_autodocs/configuration.md

Configure the debounce delay for asynchronous command processes. The process starts only after N seconds of no new input, helping to avoid frequent process starts while typing.

```elisp
(setq consult-async-input-debounce 0.1)  ; Start sooner
```

```elisp
(setq consult-async-input-debounce 0.5)  ; Wait longer for stable input
```

--------------------------------

### Integration with Marginalia

Source: https://github.com/minad/consult/blob/main/_autodocs/README.md

Adds annotations to completion candidates using the Marginalia package. Requires Marginalia to be installed and enabled.

```elisp
(use-package marginalia :init (marginalia-mode))
```

--------------------------------

### Get System Recent Files

Source: https://github.com/minad/consult/wiki/Home.org

Retrieves a list of files recently used by the system, with specific handling for GNU/Linux systems.

```emacs-lisp
(defun consult--recent-system-files ()
  "Return a list of files recently used by the system."
  (cl-case system-type
    (gnu/linux
     (consult--xdg-recent-file-list))
    (t
     (message "consult-recent-file: \"%s\" currently unsupported"
              system-type)
     '())))
```

--------------------------------

### Creating Simple Commands with consult--read (String List)

Source: https://github.com/minad/consult/blob/main/README.org

Demonstrates how to use consult--read to create a simple command that prompts the user to select from a list of strings. The :sort nil option disables sorting, and :prompt sets the displayed prompt message.

```emacs-lisp
(consult--read
 '("String A"
   "String B"
   "String C")
 :sort nil
 :prompt "Select: ")
```

--------------------------------

### Load a theme with live preview

Source: https://github.com/minad/consult/blob/main/_autodocs/api-reference/consult-modes-commands.md

Disables all currently active themes and enables the selected one, providing live preview as you navigate completions. The themes shown are determined by `consult-themes`.

```elisp
(consult-theme)
```

--------------------------------

### consult-isearch-backward

Source: https://github.com/minad/consult/blob/main/_autodocs/api-reference/consult-isearch.md

Continues or starts an incremental search backward. It can optionally reverse the search direction. This command is useful when bound to a key in `isearch-mode-map`.

```APIDOC
## consult-isearch-backward

### Description

Continues or starts an incremental search backward. Can optionally reverse the search direction.

### Method

Elisp Function Call

### Parameters

#### Optional Parameters

- **reverse** (boolean) - Optional - If t, search forward instead.

### Returns

Continues or starts isearch. Returns nil.

### Example

```elisp
(define-key isearch-mode-map (kbd "M-c") #'consult-isearch-backward)
```
```

--------------------------------

### consult-isearch-forward

Source: https://github.com/minad/consult/blob/main/_autodocs/api-reference/consult-isearch.md

Continues or starts an incremental search forward. It can optionally reverse the search direction. This command is useful when bound to a key in `isearch-mode-map`.

```APIDOC
## consult-isearch-forward

### Description

Continues or starts an incremental search forward. Can optionally reverse the search direction.

### Method

Elisp Function Call

### Parameters

#### Optional Parameters

- **reverse** (boolean) - Optional - If t, search backwards instead.

### Returns

Continues or starts isearch. Returns nil.

### Example

```elisp
;; Bind in isearch map to use consult while searching
(define-key isearch-mode-map (kbd "M-c") #'consult-isearch-forward)
```
```

--------------------------------

### Configure consult-preview-partial-size

Source: https://github.com/minad/consult/blob/main/_autodocs/configuration.md

Set the file size threshold for partial previews. Files larger than this value will be previewed partially.

```elisp
(setq consult-preview-partial-size (* 5 1024 1024))  ; 5 MB
```

--------------------------------

### Grep with Custom Directories

Source: https://github.com/minad/consult/blob/main/_autodocs/README.md

Initiates a grep search. Use C-u prefix to manually specify directories or C-u C-u to choose from known projects.

```elisp
(consult-grep)
```

--------------------------------

### consult-ripgrep search with initial input

Source: https://github.com/minad/consult/blob/main/_autodocs/api-reference/consult-search.md

Starts a ripgrep search with a predefined initial string, such as 'error'. This pre-populates the search query for faster results.

```elisp
(consult-ripgrep nil "error")
```

--------------------------------

### Consult with Live Preview

Source: https://github.com/minad/consult/blob/main/README.org

Integrate a live preview function with `consult--read` using the `:state` parameter. This enables real-time preview of completion candidates as the user types.

```emacs-lisp
(consult--read
 (consult--dynamic-collection
  (lambda (input callback)
    (dotimes (i 3)
      (sleep-for 0.1) ;; Simulate work
      (funcall callback (mapcar (lambda (s) (format "%s%s" s i))
                                (split-string input nil t))))))
 :prompt "run testibus: "
 :state #'testibus--preview)
```

--------------------------------

### Configure consult-preview-key

Source: https://github.com/minad/consult/blob/main/_autodocs/configuration.md

Set the keys that trigger preview updates during completion. Can be disabled (`nil`), set to `'any`, a specific key, a list of keys, or a debounced configuration.

```elisp
(setq consult-preview-key 'any)        ; preview on any key
```

```elisp
(setq consult-preview-key "M-.")       ; only on M-.
```

```elisp
(setq consult-preview-key nil)         ; disable preview
```

```elisp
(setq consult-preview-key '("M-." "M-,"))  ; multiple keys
```

```elisp
(setq consult-preview-key '(:debounce 0.2 any))  ; debounced
```

--------------------------------

### Creating Simple Commands with consult--read (Alist)

Source: https://github.com/minad/consult/blob/main/README.org

Shows how to use consult--read with an association list (alist) where each entry is a pair of (completion-string . value). The :lookup #'consult--lookup-cdr option is used to retrieve the associated value.

```emacs-lisp
(consult--read
 '( ("String A" . value-a)
   ("String B" . value-b)
   ("String C" . value-c))
 :prompt "Select: "
 :sort nil
 :lookup #'consult--lookup-cdr)
```

--------------------------------

### Get tab object from index

Source: https://github.com/minad/consult/wiki/Home.org

Retrieves the tab object from the `tab-bar-tabs` list using a given index. This allows access to tab properties.

```emacs-lisp
(defun +tab-bar--tab-from-index (index)
  "Return tab from `(tab-bar-tabs)' by index of CAND."
  (when index
    (nth (1- index) (tab-bar-tabs))))
```

--------------------------------

### Buffer and File Selection Commands

Source: https://github.com/minad/consult/blob/main/_autodocs/README.md

Commands for enhanced buffer switching and file selection, including project-specific and recent file options.

```APIDOC
## Buffer and File Selection

### `consult-buffer`
Enhanced buffer switcher with virtual buffers.

### `consult-buffer-other-window` / `-other-frame` / `-other-tab`
Variants for switching buffers in different window or frame configurations.

### `consult-project-buffer`
Project-focused buffer switcher.

### `consult-recent-file`
Select from a list of recently accessed files.

### `consult-bookmark`
Browse and create bookmarks for various types (file, web, mail, etc.).
```

--------------------------------

### Configure consult-project-buffer Sources

Source: https://github.com/minad/consult/blob/main/_autodocs/api-reference/consult-buffer.md

Sets the list of virtual buffer sources specifically for the consult-project-buffer command. This allows for project-specific buffer selection.

```elisp
(setq consult-project-buffer-sources
      '(consult-source-project-buffer
        consult-source-project-recent-file
        consult-source-project-root))
```

--------------------------------

### consult-line

Source: https://github.com/minad/consult/blob/main/_autodocs/api-reference/consult-search.md

Searches for a matching line within the current buffer. It allows live preview and can start the search from the top or the current line. Cursor placement can be configured.

```APIDOC
## consult-line

### Description
Search for a matching line in the current buffer. Enters search string and selects from matching lines with live preview. The symbol at point and recent Isearch string are available via `M-n` (future history). When bound to `isearch-mode-map`, it will use the current Isearch string as initial input. The command respects `consult-point-placement` for where to leave the cursor.

### Parameters

#### Path Parameters
- **initial** (string) - Optional - Initial search string
- **start** (boolean) - Optional - If t, start search from top; if nil, start from current line

### Returns
Jumps to selected line. Returns nil.

### Example

```elisp
(consult-line)
(consult-line "TODO")
```
```

--------------------------------

### Project Integration for Grep and Buffers

Source: https://github.com/minad/consult/blob/main/_autodocs/README.md

Configures Consult to search within the current project and display project-related buffers and files. Sets the project detection function.

```elisp
;; consult-grep searches current project
;; consult-project-buffer shows project buffers/files
;; Customize project detection:
(setq consult-project-function #'consult--default-project-function)  ; project.el
```

--------------------------------

### Basic consult-project-buffer Usage

Source: https://github.com/minad/consult/blob/main/_autodocs/api-reference/consult-buffer.md

Initiates the consult-project-buffer command for switching to a buffer within the current project. This command is project-focused and may prompt for a project directory if invoked outside a project context.

```elisp
(call-interactively #'consult-project-buffer)
```

--------------------------------

### Switch Project Buffers

Source: https://github.com/minad/consult/blob/main/_autodocs/00-START-HERE.md

Opens the Consult interface to switch between buffers within the current project only.

```elisp
(consult-project-buffer)   ; project buffers only
```

--------------------------------

### Get recent tab completion list

Source: https://github.com/minad/consult/wiki/Home.org

Retrieves a completion list of recently used tabs, excluding the current one. Useful for quickly switching to other tabs.

```emacs-lisp
(defun +tab-bar--completion-list-recent () 
  "Return completion list of recent tabs (current not included)."
  (+tab-bar--make-completion-list (tab-bar--tabs-recent)))
```

--------------------------------

### Eww Bookmark Source for Consult

Source: https://github.com/minad/consult/wiki/Home.org

Integrates Eww bookmarks into Consult's buffer sources. Requires `eww` and uses `eww-read-bookmarks` to populate the source. The action navigates to the bookmarked URL.

```emacs-lisp
(require 'eww)

(defvar consult--source-eww
  (list
   :name     "Eww"
   :narrow   ?e
   :action   (lambda (bm) (eww-browse-url (get-text-property 0 'url bm)))
   :items    (lambda () (eww-read-bookmarks) (mapcar (lambda (bm) (propertize (format "%s (%s)" (plist-get bm :url) (plist-get bm :title)) 'url (plist-get bm :url))) eww-bookmarks))))

(add-to-list 'consult-buffer-sources 'consult--source-eww 'append)
```

--------------------------------

### Tool Configuration for Grep and Find

Source: https://github.com/minad/consult/blob/main/_autodocs/README.md

Configures Consult to use ripgrep instead of grep and fd instead of find for faster searching. Also shows how to customize grep arguments, including exclusions.

```elisp
;; Use ripgrep instead of grep (faster)
(setq consult-ripgrep-args "rg --...")

;; Or use fd instead of find
(setq consult-fd-args "fd --...")

;; Customize grep exclusions
(setq consult-grep-args '("grep" (consult--grep-exclude-args) ...))
```

--------------------------------

### consult-project-buffer

Source: https://github.com/minad/consult/blob/main/_autodocs/api-reference/consult-buffer.md

An enhanced `project-switch-to-buffer` command that supports virtual buffers within the current project.

```APIDOC
## consult-project-buffer

### Description

Enhanced `project-switch-to-buffer` command with support for virtual buffers. This is a project-focused variant of `consult-buffer`. The command may prompt for a project directory if invoked from outside a project context. It uses the sources defined in `consult-project-buffer-sources` instead of the global `consult-buffer-sources`.

### Signature

```elisp
(consult-project-buffer)
```

### Parameters

None.

### Returns

Switches to selected buffer in current project. Returns nil.

### Example

```elisp
(call-interactively #'consult-project-buffer)
```
```

--------------------------------

### Immediate Which-Key Help for Narrowing

Source: https://github.com/minad/consult/wiki/Home.org

Ensures the which-key menu appears immediately after invoking consult-narrow-key. This uses advice to add a small timer that triggers the menu update.

```elisp
(defun immediate-which-key-for-narrow (fun &rest args)
    (let* ((refresh t)
           (timer (and consult-narrow-key
                       (memq :narrow args)
                       (run-at-time 0.05 0.05
                                    (lambda () 
                                      (if (eq last-input-event (elt consult-narrow-key 0))
                                          (when refresh
                                            (setq refresh nil)
                                            (which-key--update))
                                        (setq refresh t)))))))
      (unwind-protect
          (apply fun args)
        (when timer
          (cancel-timer timer)))))
  (advice-add #'consult--read :around #'immediate-which-key-for-narrow)
```

--------------------------------

### Initial Narrowing for ERC Buffers

Source: https://github.com/minad/consult/wiki/Home.org

This function narrows the buffer list to only show ERC-related candidates when the 'ERC' tab is active in the tab bar. It's triggered on minibuffer setup.

```elisp
(defun consult-initial-narrow () (when (and (eq this-command #'consult-buffer) (string-equal "ERC" (alist-get 'name (alist-get 'current-tab (tab-bar-tabs))))) (setq unread-command-events (append unread-command-events (list ?e 32)))))

(add-hook 'minibuffer-setup-hook #'consult-initial-narrow)
```

--------------------------------

### Configure Default Completion UI Settings

Source: https://github.com/minad/consult/blob/main/README.org

Set up the default Emacs completion UI for a one-column view with annotations, sorted by history, and eager updates. This configuration aims for performance and an intuitive user experience.

```emacs-lisp
(setq
 ;; One column view with annotations
 completions-format 'one-column
 completions-detailed t
 completions-group t
 ;; Sort candidates by history position
 completions-sort 'historical
 ;; Allow navigating from the minibuffer
 minibuffer-visible-completions 'up-down
 ;; Show completions eagerly and update automatically
 completion-eager-update t
 completion-eager-display t
 completion-auto-help 'always
 ;; Disable noise in the *Completions* buffer
 completion-show-help nil)
```

```emacs-lisp
;; Unbind `minibuffer-complete-word'
(keymap-unset minibuffer-local-completion-map "SPC")
```

--------------------------------

### Add Command-Local Keybinding for Consult Line

Source: https://github.com/minad/consult/wiki/Home.org

Binds a key in a command-local keymap to load the latest search term when pressing a specific key combination. This example binds C-s in consult-line to previous-history-element.

```elisp
(defvar my-consult-line-map
    (let ((map (make-sparse-keymap)))
      (define-key map "\C-s" #'previous-history-element)
      map))

  (consult-customize consult-line :keymap my-consult-line-map)

```

--------------------------------

### consult-theme

Source: https://github.com/minad/consult/blob/main/_autodocs/api-reference/consult-modes-commands.md

Loads a theme with live preview. It disables all currently active themes and enables the selected one, offering a live preview as you navigate through theme options. The available themes can be configured via `consult-themes`.

```APIDOC
## consult-theme

### Description
Load a theme with live preview. Disables current themes and enables the selected theme. Provides live preview of the theme as you navigate completions. Useful for quickly switching between color schemes. The themes shown are determined by `consult-themes`. If nil (default), shows all available themes from `custom-available-themes`.

### Signature
```elisp
(consult-theme theme)
```

### Parameters
#### Path Parameters
- **theme** (symbol) - Required - Theme name to load

### Returns
Disables current themes and enables the selected theme. Returns nil.

### Example
```elisp
(consult-theme)
;; Shows all available themes
;; Select to preview and load it
;; Disables previously active themes
```
```

--------------------------------

### Configure Project Root Function in Consult

Source: https://github.com/minad/consult/blob/main/README.org

Set the `consult-project-function` to customize how Consult discovers the project root. Examples show using project.el, vc.el, locate-dominating-file, projectile.el, or disabling project support.

```emacs-lisp
;; Optionally configure a different project root function.
;; 1. project.el (the default)
(setq consult-project-function #'consult--default-project--function)
;; 2. vc.el (vc-root-dir)
(setq consult-project-function (lambda (_) (vc-root-dir)))
;; 3. locate-dominating-file
(setq consult-project-function (lambda (_) (locate-dominating-file "." ".git")))
;; 4. projectile.el (projectile-project-root)
(autoload 'projectile-project-root "projectile")
(setq consult-project-function (lambda (_) (projectile-project-root)))
;; 5. Disable project support
(setq consult-project-function nil)
```

--------------------------------

### Select Themes for consult-theme

Source: https://github.com/minad/consult/blob/main/_autodocs/configuration.md

Configure which themes are displayed in `consult-theme`. You can provide a list of theme symbols, regular expressions to match theme names, or `nil` to show all available themes.

```elisp
(setq consult-themes '(modus-operandi modus-vivendi doom-one))
```

```elisp
(setq consult-themes '("doom" "modus"))  ; as regexps
```

```elisp
(setq consult-themes nil)  ; show all available themes
```

--------------------------------

### Allow Custom Hooks for Consult Previews

Source: https://github.com/minad/consult/blob/main/README.org

Add custom modes to the list of allowed hooks for Consult previews to enable features like font locking. This example adds `hl-todo-mode` and `elide-head-mode`.

```emacs-lisp
;; local modes added to prog-mode hooks
(add-to-list 'consult-preview-allowed-hooks 'hl-todo-mode)
(add-to-list 'consult-preview-allowed-hooks 'elide-head-mode)
;; enabled global modes
(add-to-list 'consult-preview-allowed-hooks 'global-org-modern-mode)
(add-to-list 'consult-preview-allowed-hooks 'global-hl-todo-mode)
```

--------------------------------

### Set Consult Async Minimum Input Length

Source: https://github.com/minad/consult/blob/main/_autodocs/configuration.md

Define the minimum input length required before an asynchronous process starts. This prevents searching for very broad patterns by ensuring at least N characters are entered.

```elisp
(setq consult-async-min-input 1)  ; Start immediately
```

```elisp
(setq consult-async-min-input 5)  ; Require 5 characters
```

--------------------------------

### Initialize Consult and Marginalia for tab completion

Source: https://github.com/minad/consult/wiki/Home.org

Loads the necessary Consult and Marginalia libraries for enhanced tab completion. This is a prerequisite for using the tab completion features.

```emacs-lisp
(require 'consult)
(require 'marginalia)
```

--------------------------------

### Dynamic Completion Candidates with Simulated Work

Source: https://github.com/minad/consult/blob/main/README.org

Utilize `consult--dynamic-collection` to generate completion candidates directly from an Emacs Lisp function. This example simulates work using `sleep-for` and splits the input string into a list.

```emacs-lisp
(consult--read
 (consult--dynamic-collection
  (lambda (input)
    (sleep-for 0.1) ;; Simulate work
    (split-string input nil t)))
 :prompt "run testibus: ")
```

--------------------------------

### Use Enhanced Register Preview Window

Source: https://github.com/minad/consult/blob/main/_autodocs/api-reference/consult-navigation.md

Replace the default `register-preview-function` with `consult-register-window` to utilize an enhanced drop-in replacement for the built-in register preview window. This provides better formatting and display of register contents.

```elisp
;; Set as the register preview function
(setq register-preview-function #'consult-register-window)
```

--------------------------------

### Configure Buffer Sources

Source: https://github.com/minad/consult/blob/main/_autodocs/configuration.md

Define the list of virtual buffer sources to include in the `consult-buffer` command. This allows customization of which buffer types are searchable.

```emacs-lisp
(setq consult-buffer-sources
      '(consult-source-buffer
        consult-source-hidden-buffer
        consult-source-modified-buffer
        consult-source-recent-file
        consult-source-bookmark
        consult-source-project-buffer-hidden))
```

--------------------------------

### Customize Consult Preview Behavior

Source: https://github.com/minad/consult/blob/main/_autodocs/00-START-HERE.md

Control when the live preview of search results is displayed. Setting to 'any' shows preview on any key press, while 'nil' disables it.

```elisp
(setq consult-preview-key 'any)   ; preview on any key
```

```elisp
(setq consult-preview-key nil)    ; disable preview
```

--------------------------------

### Custom project-find-file with preview

Source: https://github.com/minad/consult/wiki/Home.org

Enables file previews for `project.el` by setting `project-read-file-name-function`. It customizes the prompt based on the directory and uses `consult--read` for completion.

```emacs-lisp
(setq project-read-file-name-function #'consult-project-find-file-with-preview)

(defun consult-project-find-file-with-preview (prompt all-files &optional pred hist _mb)
  (let ((prompt (if (and all-files
                         (file-name-absolute-p (car all-files)))
                    prompt
                  ( concat prompt
                    ( format " in %s"
                      (consult--fast-abbreviate-file-name default-directory))))))
        (minibuffer-completing-file-name t))
    (consult--read (mapcar
                    (lambda (file)
                      (file-relative-name file))
                    all-files)
                   :state (consult--file-preview)
                   :prompt (concat prompt ": ")
                   :require-match t
                   :history hist
                   :category 'file
                   :predicate pred)))
```

--------------------------------

### Configure Consult Project Function

Source: https://github.com/minad/consult/blob/main/_autodocs/configuration.md

Specify the function that determines the project root directory for commands like `consult-grep` and `consult-buffer`. The function can prompt the user if `may-prompt` is non-nil and should return the absolute path to the project root or nil.

```elisp
;; Use Emacs' built-in project.el (default):
(setq consult-project-function #'consult--default-project-function)
```

```elisp
;; Disable project integration:
(setq consult-project-function nil)
```

```elisp
;; Use a custom function:
(setq consult-project-function
      (lambda (may-prompt)
        (when-let ((root (vc-git-root (or buffer-file-name default-directory))))
          (expand-file-name root))))
```

--------------------------------

### Implement hrm-notes functionality

Source: https://github.com/minad/consult/wiki/hrm-notes

Full implementation of the hrm-notes package, including source definition, annotation logic, and Embark integration.

```emacs-lisp
(require 'consult)
(require 'marginalia)			; for faces
(require 'embark)

(defvar hrm-notes-category 'hrm-note
  "Category symbol for the notes in this package.")

(defvar hrm-notes-history nil
  "History variable for hrm-notes.")

(defvar hrm-notes-sources-data
  '(("Restaurants"   ?r "~/Dropbox/Restaurants/")
    ("Lectures"      ?l "~/Dropbox/Lectures/")
    ("Simplenotes"   ?s "~/Library/Application Support/Notational Data/")))

(defun hrm-notes-make-source (name char dir)
  "Return a notes source list suitable for `consult--multi'.
NAME is the source name, CHAR is the narrowing character,
and DIR is the directory to find notes. "
  (let ((idir (propertize (file-name-as-directory dir) 'invisible t)))
    `(:name     ,name
      :narrow   ,char
      :category ,hrm-notes-category
      :face     consult-file
      :annotate ,(apply-partially 'hrm-annotate-note name)
      :items    ,(lambda () (mapcar (lambda (f) (concat idir f))
				    ;; filter files that glob *.*
				    (directory-files dir nil "[^.].*[.].+")))
      :action   ,(lambda (f) (find-file f) (markdown-mode)))))
      ;; :action   find-file)))  ; use this if you don't want to force markdown-mode

(defun hrm-annotate-note (name cand)
  "Annotate file CAND with its source name, size, and modification time."
  (let* ((attrs (file-attributes cand))
	 (fsize (file-size-human-readable (file-attribute-size attrs)))
	 (ftime (format-time-string "%b %d %H:%M" (file-attribute-modification-time attrs))))
    (put-text-property 0 (length name) 'face 'marginalia-type name)
    (put-text-property 0 (length fsize) 'face 'marginalia-size fsize)
    (put-text-property 0 (length ftime) 'face 'marginalia-date ftime)
    (format "%15s  %7s  %10s" name fsize ftime)))

(defun hrm-notes ()
  "Find a file in a notes directory."
  (interactive)
  (let ((completion-ignore-case t))
    (consult--multi (mapcar #'(lambda (s) (apply #'hrm-notes-make-source s))
                            hrm-notes-sources-data)
                    :prompt "Notes File: "
                    :group nil
                    :history 'hrm-notes-history)))

;;;; embark support

(defun hrm-notes-dired (cand)
  "Open notes directory dired with point on file CAND."
  (interactive "fNote: ")
  ;; dired-jump is in dired-x.el but is moved to dired in Emacs 28
  (dired-jump nil cand))

(defun hrm-notes-marked (cand)
  "Open a notes file CAND in Marked 2."
  (interactive "fNote: ")
  ;; Marked 2 is a mac app that renders markdown
  (call-process-shell-command (format "open -a \"Marked 2\" \"%s\"" (expand-file-name cand))))

(defun hrm-notes-grep (cand)
  "Run consult-ripgrep in directory of notes file CAND."
  (interactive "fNote: ")
  (consult-ripgrep (file-name-directory cand)))

(embark-define-keymap hrm-notes-map
  "Keymap for Embark notes actions."
  :parent embark-file-map
  ("d" hrm-notes-dired)
  ("g" hrm-notes-grep)
  ("m" hrm-notes-marked))

(add-to-list 'embark-keymap-alist `(,hrm-notes-category . hrm-notes-map))
;; make embark-export use dired for notes
(setf (alist-get hrm-notes-category embark-exporters-alist) #'embark-export-dired)
```

--------------------------------

### Define Live Preview Function for Consult

Source: https://github.com/minad/consult/blob/main/README.org

Define a preview function `testibus--preview` that handles preview actions. It displays the input candidate in a dedicated buffer named " *testibus*".

```emacs-lisp
(defun testibus--preview (action cand)
  (pcase action
    ('preview
     (with-current-buffer-window " *testibus*" 'action nil
       (erase-buffer)
       (insert (format "input: %s\n" cand))))))
```

--------------------------------

### Consult API Reference Overview

Source: https://github.com/minad/consult/blob/main/_autodocs/_DOCUMENTATION_SUMMARY.txt

This section outlines the structure and navigation of the Consult API reference documentation. It details how to find information on commands, configuration, and data structures, and provides quick navigation links to specific modules.

```APIDOC
## Consult API Reference

This document serves as a technical reference for the Consult API. It is organized to provide direct access to information about the API's surface, including commands, configuration options, and data types.

### How to Use This Reference

- **Finding Commands**: Use `COMMAND-INDEX.md` to locate commands and navigate to their respective API reference files.
- **Configuration**: Refer to `configuration.md` for documentation on configuration variables and their usage examples.
- **Data Structures**: Consult `types.md` for definitions of data structures and information on functions that utilize them.
- **Getting Started**: Begin with `00-START-HERE.md`, followed by `README.md`, and then use `COMMAND-INDEX.md` for exploration.

### Quick Navigation

- **Buffer operations**: `api-reference/consult-buffer.md`
- **Search operations**: `api-reference/consult-search.md`
- **Navigation**: `api-reference/consult-navigation.md`
- **Editing/kill ring**: `api-reference/consult-editing.md`
- **Configuration**: `configuration.md`
- **Data types**: `types.md`
- **Complete index**: `INDEX.md`
- **All commands**: `COMMAND-INDEX.md`

### API Reference Directory Structure

- `api-reference/consult-buffer.md`: Buffer switching commands.
- `api-reference/consult-search.md`: Search and grep commands.
- `api-reference/consult-navigation.md`: Navigation and jumping commands.
- `api-reference/consult-editing.md`: Editing and kill ring commands.
- `api-reference/consult-isearch.md`: Isearch integration.
- `api-reference/consult-modes-commands.md`: Mode and command selection.
- `api-reference/consult-compilation.md`: Compilation error navigation.
- `api-reference/consult-extensions.md`: Specialized extensions.
```

--------------------------------

### Basic consult-buffer Usage

Source: https://github.com/minad/consult/blob/main/_autodocs/api-reference/consult-buffer.md

Initiates the consult-buffer command for basic buffer switching with completion. This is the most straightforward way to use the command.

```elisp
(call-interactively #'consult-buffer)
```

--------------------------------

### Enable File Preview in find-file

Source: https://github.com/minad/consult/wiki/Home.org

Configures Consult to provide a preview of files within the find-file command. This requires setting a custom read-file-name-function.

```elisp
(setq read-file-name-function #'consult-find-file-with-preview)

(defun consult-find-file-with-preview (prompt &optional dir default mustmatch initial pred)
  (interactive)
  (let ((default-directory (or dir default-directory))
        (minibuffer-completing-file-name t))
    (consult--read #'read-file-name-internal :state (consult--file-preview)
                   :prompt prompt
                   :initial initial
                   :require-match mustmatch
                   :predicate pred)))
```