### Consult-GH Transient Menu Setup

Source: https://github.com/armindarvish/consult-gh/blob/main/_autodocs/api-reference-integration-modules.md

Example setup for the `consult-gh-transient` module, which provides a menu-driven interface. This snippet shows how to bind the transient menu to a key.

```elisp
(use-package consult-gh-transient
  :after consult-gh
  :config
  ;; Add transient menu binding to your prefix
  (global-set-key (kbd "C-c g") 'consult-gh-transient-menu))
```

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

### Complete Integration Setup

Source: https://github.com/armindarvish/consult-gh/blob/main/_autodocs/api-reference-integration-modules.md

An example configuration enabling all optional consult-gh modules. This includes core, embark, forge, PR review, nerd icons, and transient menus.

```elisp
;; Core consult-gh
(use-package consult-gh
  :after consult
  :custom
  (consult-gh-maxnum 50))

;; Embark integration for context menus
(use-package consult-gh-embark
  :after consult-gh
  :config
  (consult-gh-embark-mode +1))

;; Magit/Forge integration
(use-package consult-gh-forge
  :after (consult-gh magit forge)
  :config
  (consult-gh-forge-mode +1))

;; PR Review integration
(use-package consult-gh-with-pr-review
  :after (consult-gh pr-review)
  :config
  (consult-gh-with-pr-review-mode +1))

;; Nerd icons support
(use-package consult-gh-nerd-icons
  :after (consult-gh nerd-icons)
  :config
  (consult-gh-nerd-icons-mode +1)
  :custom
  (consult-gh-nerd-icons-use-icons t))

;; Transient menu interface
(use-package consult-gh-transient
  :after (consult-gh transient)
  :bind
  ("C-c g" . consult-gh-transient-menu))
```

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

### Minimal consult-gh Setup

Source: https://github.com/armindarvish/consult-gh/blob/main/_autodocs/README.md

This is the most basic setup for consult-gh, requiring only the consult package to be already loaded.

```emacs-lisp
(use-package consult-gh
  :after consult)
```

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

### Set All Fields Example

Source: https://github.com/armindarvish/consult-gh/blob/main/consult-gh.org

Placeholder for a function that sets all fields. This snippet is a starting point and likely requires further implementation.

```emacs-lisp

```

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

### Install Consult-GH with Straight.el (Direct)

Source: https://github.com/armindarvish/consult-gh/blob/main/README.org

Installs consult-gh using straight.el by specifying the git type, host, repository, and branch. Ensure 'consult' is loaded before consult-gh.

```emacs-lisp
(straight-use-package
 '(consult-gh :type git :host github :repo "armindarvish/consult-gh" :branch "main"))
```

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

### Install consult-gh with use-package

Source: https://github.com/armindarvish/consult-gh/blob/main/_autodocs/README.md

Install consult-gh using the use-package macro. Sets the maximum number of results to 50.

```elisp
(use-package consult-gh
  :after consult
  :custom
  (consult-gh-maxnum 50))
```

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

### Recommended consult-gh Setup

Source: https://github.com/armindarvish/consult-gh/blob/main/_autodocs/README.md

This setup includes recommended customizations for consult-gh, such as setting the maximum number of results, enabling previews, and specifying a default clone directory.

```emacs-lisp
(use-package consult-gh
  :after consult
  :custom
  (consult-gh-maxnum 50)
  (consult-gh-show-preview t)
  (consult-gh-default-clone-directory "~/projects/"))
```

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

### Full consult-gh Setup with All Modules

Source: https://github.com/armindarvish/consult-gh/blob/main/_autodocs/README.md

This comprehensive setup includes consult-gh along with optional modules for embark, forge, and nerd-icons integration, enabling advanced features and UI enhancements.

```emacs-lisp
(use-package consult-gh
  :after consult
  :custom
  (consult-gh-maxnum 50)
  (consult-gh-favorite-orgs-list '("emacs-mirror" "golang")))

(use-package consult-gh-embark
  :after consult-gh
  :config (consult-gh-embark-mode +1))

(use-package consult-gh-forge
  :after (consult-gh magit)
  :config (consult-gh-forge-mode +1))

(use-package consult-gh-nerd-icons
  :after (consult-gh nerd-icons)
  :config (consult-gh-nerd-icons-mode +1))
```

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

### Install Consult-GH Core Package with use-package

Source: https://github.com/armindarvish/consult-gh/blob/main/README.org

Installs the core consult-gh package using the use-package macro. Ensure 'consult' is loaded beforehand.

```emacs-lisp
(use-package consult-gh
:after consult)
```

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

### Setup Embark Integration

Source: https://github.com/armindarvish/consult-gh/blob/main/_autodocs/api-reference-integration-modules.md

Enables the consult-gh-embark mode for context menu actions. Ensure consult-gh is loaded first.

```elisp
(use-package consult-gh-embark
  :after consult-gh
  :config
  (consult-gh-embark-mode +1))
```

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

### Install Consult-GH with Straight.el and use-package

Source: https://github.com/armindarvish/consult-gh/blob/main/README.org

Installs consult-gh using use-package with straight.el integration. It also loads necessary extensions and enables their modes. Ensure 'consult' is loaded first.

```emacs-lisp
(use-package consult-gh
  :straight (consult-gh :type git :host github :repo "armindarvish/consult-gh")
  :after consult
  :config
  (require 'consult-gh-transient)
  (require 'consult-gh-embark)
  (require 'consult-gh-forge)
  (consult-gh-embark-mode +1)
  (consult-gh-forge-mode +1))
```

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

### Setup consult-gh-forge module

Source: https://github.com/armindarvish/consult-gh/blob/main/_autodocs/api-reference-integration-modules.md

Configure the consult-gh-forge module to integrate with Magit/Forge. Ensure consult-gh is loaded before this module.

```elisp
(use-package consult-gh-forge
  :after consult-gh
  :config
  (consult-gh-forge-mode +1))
```

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

### Full Consult GH Configuration Example

Source: https://github.com/armindarvish/consult-gh/blob/main/_autodocs/configuration.md

An example Emacs Lisp configuration for the consult-gh package using use-package. It demonstrates how to set maximum results, configure file handling, display preferences, browser and buffer switching functions, dashboard sources, and favorite organizations.

```elisp
(use-package consult-gh
  :after consult
  :custom
  ;; Set maximum results
  (consult-gh-maxnum 50)
  (consult-gh-comments-maxnum 20)
  
  ;; Configure file handling
  (consult-gh-default-clone-directory "~/projects/")
  (consult-gh-tempdir "~/.cache/consult-gh/")
  (consult-gh-confirm-before-clone t)
  
  ;; Configure display
  (consult-gh-show-preview t)
  (consult-gh-issues-state-to-show "open")
  (consult-gh-issues-show-comments-in-view 10)
  
  ;; Configure browser
  (consult-gh-browse-url-func #'eww-browse-url)
  
  ;; Configure buffer switching
  (consult-gh-switch-to-buffer-func #'switch-to-buffer-other-window)
  
  ;; Configure dashboard sources
  (consult-gh-dashboard-items-sources (list 'consult-gh--dashboard-assigned-to-user
                                            'consult-gh--dashboard-authored-by-user))
  
  ;; Configure favorite organizations
  (consult-gh-favorite-orgs-list '("emacs-mirror" "golang" "torvalds")))
```

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

### Verify gh CLI Installation

Source: https://github.com/armindarvish/consult-gh/blob/main/_autodocs/README.md

Before using consult-gh, ensure the GitHub CLI is installed and authenticated. Run this command in your terminal.

```shell
gh auth login
```

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

### Get Nerd Icon Face for Repository

Source: https://github.com/armindarvish/consult-gh/blob/main/_autodocs/api-reference-integration-modules.md

Example of getting the face for repository icons. This demonstrates how to use `consult-gh-nerd-icons-get-face` with a specific symbol.

```elisp
;; Get face for repository icons
(consult-gh-nerd-icons-get-face 'repo)
```

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

### Get File Name Position

Source: https://github.com/armindarvish/consult-gh/blob/main/consult-gh.org

Retrieves the starting position of a file name on a given line in Dired mode. Defaults to the current cursor position.

```emacs-lisp
(defun consult-gh--dired-file-name-position (&optional pos) "Get the position of beginning of the file name at POS.

POS defaults to current point."
  (save-excursion
    (when pos (goto-char pos))
    (goto-char (line-beginning-position))
    (next-single-property-change (point) :consult-gh-dired-file-name-begin nil (line-end-position))))
```

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

### Setup consult-gh-with-pr-review module

Source: https://github.com/armindarvish/consult-gh/blob/main/_autodocs/api-reference-integration-modules.md

Configure the consult-gh-with-pr-review module for enhanced PR viewing and commenting with the pr-review package. Ensure consult-gh is loaded first.

```elisp
(use-package consult-gh-with-pr-review
  :after consult-gh
  :config
  (consult-gh-with-pr-review-mode +1))
```

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

### File Candidate Properties Example

Source: https://github.com/armindarvish/consult-gh/blob/main/_autodocs/types-and-data-structures.md

Presents the text properties for file candidates, detailing class, repository, file name, path, reference (branch/tag), size, mode, type, and URL.

```elisp
;; Example file candidate properties
:class "file"
:repo "golang/go"
:file "README.md"
:path "src/cmd/"
:ref "main"
:size 1234
:mode "100644"
:type "blob"
:url "https://github.com/golang/go/blob/main/README.md"

```

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

### Get Starter Workflows

Source: https://github.com/armindarvish/consult-gh/blob/main/consult-gh.org

Searches for starter workflows based on user input. It filters a list of files to find YAML files that match the input and are not within a .github directory.

```emacs-lisp
(defun consult-gh--workflow-get-stater-workflows (input)
  "Search starter-workflows for INPUT."
  (let* ((files (consult-gh--files-list-items "actions/starter-workflows" nil nil nil "2m"))
         (workflows (and (listp files)
                          (remove nil
                                  (mapcar
                                   (lambda (item) (if (and
                                                       (string-match ".*.yml" (car item))
                                                       (not (string-match "\.github" (car item)))
                                                       (string-match (format ".*%s.*" input) (car item)))
                                                               item))
                                   files))))))
    workflows))
```

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

### Enable Magit/Forge Integration

Source: https://github.com/armindarvish/consult-gh/blob/main/README.org

Enables consult-gh-forge integration. Install from MELPA or add to your package manager configuration. Ensure Magit and Forge are installed and configured.

```emacs-lisp
(consult-gh-forge-mode +1)
```

```emacs-lisp
(use-package consult-gh-forge
  :config
  (consult-gh-forge-mode +1))
```

```emacs-lisp
(require 'consult-gh-forge)
(consult-gh-forge-mode +1)
```

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

### Install Consult-GH Forge Integration

Source: https://github.com/armindarvish/consult-gh/blob/main/README.org

Installs the consult-gh-forge integration for use with magit/forge. This package is not yet merged on MELPA. It requires consult-gh to be loaded first.

```emacs-lisp
(use-package consult-gh-forge
:after consult-gh
:config
(consult-gh-forge-mode +1))
```

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

### Install Consult-GH Embark Extension

Source: https://github.com/armindarvish/consult-gh/blob/main/README.org

Installs the consult-gh-embark extension, which adds embark actions. This package is not yet merged on MELPA. It requires consult-gh to be loaded first.

```emacs-lisp
(use-package consult-gh-embark
:after consult-gh
:config
(consult-gh-embark-mode +1))
```

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

### ISO 8601 Timestamp Format Examples

Source: https://github.com/armindarvish/consult-gh/blob/main/_autodocs/types-and-data-structures.md

Examples of ISO 8601 formatted timestamps. Used for date and time fields across various data structures.

```text
2024-01-20T15:45:00Z
2024-01-20T15:45:00+00:00
```

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

### API GET Request Command String

Source: https://github.com/armindarvish/consult-gh/blob/main/consult-gh.org

Constructs the command string for a GitHub API GET request with pagination. Used for fetching data from specified URLs with arguments.

```emacs-lisp
(let ((args (append `("api" "-H" "Accept: application/vnd.github+json" "--paginate" ,url) (if (listp args) args (list args))))) (apply #'consult-gh--command-to-string args))
```

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

### Repository Candidate Properties Example

Source: https://github.com/armindarvish/consult-gh/blob/main/_autodocs/types-and-data-structures.md

Illustrates the common text properties applied to repository candidates, including class, repo name, user, title, URL, description, language, star count, fork count, watcher count, and fork/archive status.

```elisp
;; Example repository candidate properties
:class "repo"
:repo "golang/go"
:user "golang"
:title "The Go programming language"
:url "https://github.com/golang/go"
:description "The Go programming language"
:lang "Go"
:stars 123456
:forks 34567
:watchers 4567

```

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

### Create New GitHub Repository from Scratch

Source: https://github.com/armindarvish/consult-gh/blob/main/consult-gh.org

Use this function to create a new GitHub repository. It prompts for repository name, owner, description, visibility, and whether to clone it locally. Requires `consult--read` and `consult-gh--call-process`.

```emacs-lisp
(defun consult-gh--repo-create (&optional name directory owner description visibility template use-scratch) "Create a new repository on github.  Options:

  NAME        name of repository
  DIRECTORY   path to local directory to clone into
  OWNER       user/organization owning the repo
  DESCRIPTION description for the repo
  VISIBILITY  private|public|internal
  TEMPLATE    template repository to use
  USE-SCRATCH if t, create a scratch repo without template."
  (interactive "sName: ")
  (let* ((name (or name (read-string "Repository name: "))) (owner (or owner (consult--read (consult-gh--get-current-user-orgs nil t) :prompt "Repository owner: " :initial nil :sort nil :require-match t))) (targetrepo (concat (and owner (unless (string-empty-p owner) (concat owner "/"))) name)) (description (or description (read-string "Description: "))) (description (and (stringp description) (not (string-empty-p description)) description)) (visibility (or visibility (downcase (consult--read (list "Public" "Private" "Internal") :prompt "Visibility: " :sort nil :require-match t)))) (template (or template (and (not use-scratch) (consult--read (consult-gh--list-template-repos) :prompt "Select a template repository (or leave blank): " :initial nil :sort nil :require-match nil)))) (use-scratch (if (not template) (y-or-n-p "No template selected.  Would you like to make the repo without template?")))) (cond (template (let* ((confirm (y-or-n-p (format "This will create %s as a %s repository on GitHub.  Continue?" (propertize name 'face 'consult-gh-repo) (propertize visibility 'face 'warning)))) (clone (if confirm (y-or-n-p "Clone the new repository locally?"))) (clonedir (if clone (read-directory-name (format "Select Directory to clone %s in " (propertize name 'face 'font-lock-keyword-face)) (or (and (stringp consult-gh-default-clone-directory) (file-name-as-directory consult-gh-default-clone-directory)) default-directory)))) (default-directory (or clonedir default-directory)) (targetdir (expand-file-name name default-directory)) (args '("repo" "create")) (out)) (setq args (if (and targetrepo confirm visibility) (delq nil (append args (list targetrepo) (list (concat "--" visibility)) (list "--template" template) (and description (list "--description" description)) (and clone (list "--clone")))))) (setq out (apply #'consult-gh--call-process args)) (if (eq (car out) 0) (progn (when (and clone (file-exists-p targetdir)) (message "repo %s was cloned to %s" (propertize name 'face 'font-lock-keyword-face) (propertize targetdir 'face 'font-lock-type-face)) (run-hook-with-args 'consult-gh-repo-post-clone-hook targetdir)) (propertize targetrepo :type 'template :name name :owner owner :directory (and clone targetdir) :license nil :gitignore nil :make-readme nil :make-remote nil :visibiliy visibility :description description :template-repo template)) (message (cadr out))))) (use-scratch (consult-gh--repo-create-scratch name owner description visibility)) (t (message "aborted without making repository")))))
```

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

### Create Repository from Scratch

Source: https://github.com/armindarvish/consult-gh/blob/main/consult-gh.org

Function to create a new GitHub repository from scratch, accepting various configuration options.

```emacs-lisp
(defun consult-gh--repo-create-scratch (&optional name directory owner description visibility make-readme gitignore-template license-key)
  "Create a new repository on github from scratch.

Description of Arguments:

 NAME               name of repository
 DIRECTORY          path to local directory of git repository
 OWNER              user/organization owning the repo
 DESCRIPTION        description for the repo
 VISIBILITY         private|public|internal
 MAKE-README        boolean, whether to make a readme file or not
 GITIGNORE-TEMPLATE name of gitignore template
 LICENSE-KEY        key for license template"
  (let* ((name (or name (read-string "Repository name: ")))
         (owner (or owner (consult--read (consult-gh--get-current-user-orgs nil t)
                                         :prompt "Repository owner: "
                                         :initial nil
                                         :sort nil
)))
```

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

### Browse repository files

Source: https://github.com/armindarvish/consult-gh/blob/main/_autodocs/README.md

Opens a Dired-like browser for navigating repository files.

```elisp
;; Browse repository files
M-x consult-gh-dired RET
```

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

### Define consult-gh-commit-message-mode-off

Source: https://github.com/armindarvish/consult-gh/blob/main/consult-gh.org

Disables `consult-gh-commit-message-mode` by restoring the original comment start character.

```emacs-lisp
(defun consult-gh-commit-message-mode-off ()
  "Disable `consult-gh-topics-edit-mode'."
  (setq-local comment-start consult-gh--commit-comment-start-save))
```

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

### Get Username from Repository

Source: https://github.com/armindarvish/consult-gh/blob/main/consult-gh.org

Extracts the username from a repository string (e.g., 'armindarvish' from 'armindarvish/consult-gh').

```emacs-lisp
(defun consult-gh--get-username (repo)
  "Return the username of REPO.

  \(e.g. “armindarvish” if REPO is “armindarvish/consult-gh”
)"
  (car (consult-gh--split-repo repo)))
```

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

### Consult GH Repository Search and Action Workflow

Source: https://github.com/armindarvish/consult-gh/blob/main/_autodocs/api-reference-embark-actions.md

Demonstrates the typical workflow for searching GitHub repositories using Consult GH and then invoking Embark actions on the selected repository. This includes searching, navigating, and selecting actions like opening, previewing, or favoriting.

```emacs-lisp
;; 1. Search for repositories
M-x consult-gh-search-repos RET golang

;; 2. Navigate with C-n/C-p to select a repository
;; 3. Press C-. (embark-act) to show available actions
;; 4. Select an action:
;;    - Press RET for default action (open repository)
;;    - Press "p" to show preview
;;    - Press "f" to add to favorites
;;    - Press "b" to open in browser
;;    - etc.
```

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

### Code Candidate Properties Example

Source: https://github.com/armindarvish/consult-gh/blob/main/_autodocs/types-and-data-structures.md

Demonstrates the text properties used for code search results, including class, repository, file path, line number, URL, and a code snippet.

```elisp
;; Example code search result properties
:class "code"
:repo "golang/go"
:file "src/runtime/proc.go"
:line 123
:url "https://github.com/golang/go/blob/main/src/runtime/proc.go#L123"
:snippet "func procPin() { ... }"

```

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

### Get Direct URL from Candidate

Source: https://github.com/armindarvish/consult-gh/blob/main/_autodocs/types-and-data-structures.md

Obtain the direct URL associated with a candidate using `get-text-property`.

```elisp
;; Get direct URL
(get-text-property 0 :url candidate)
```

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

### Get Repository Name from Candidate

Source: https://github.com/armindarvish/consult-gh/blob/main/_autodocs/types-and-data-structures.md

Extract the repository name from a candidate using `get-text-property` and `substring-no-properties`.

```elisp
;; Get repository name from candidate
(substring-no-properties 
  (get-text-property 0 :repo candidate))
```

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

### Open Dired Browser for GitHub Repository

Source: https://github.com/armindarvish/consult-gh/blob/main/_autodocs/api-reference-dired-browser.md

Opens a dired-like buffer for navigating a GitHub repository. Prompts for repository if not specified, and uses the default branch if no ref is provided.

```elisp
(consult-gh-dired &optional repo path ref buffer no-select revert)
```

```elisp
;; Interactively browse a repository
(consult-gh-dired)

;; Browse a specific repository
(consult-gh-dired "golang/go")

;; Browse a specific branch
(consult-gh-dired "golang/go" "/" "main")

;; Browse a subdirectory
(consult-gh-dired "golang/go" "src/")
```

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

### Setup consult-gh-nerd-icons module

Source: https://github.com/armindarvish/consult-gh/blob/main/_autodocs/api-reference-integration-modules.md

Configure the consult-gh-nerd-icons module to enable Nerd Font icons in consult-gh displays. Requires the nerd-icons package and a Nerd Font.

```elisp
(use-package consult-gh-nerd-icons
  :after consult-gh
  :config
  (consult-gh-nerd-icons-mode +1))
```

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

### Enable Embark Integration

Source: https://github.com/armindarvish/consult-gh/blob/main/README.org

Enables consult-gh-embark integration. Install from MELPA or add to your package manager configuration.

```emacs-lisp
(use-package consult-gh-embark
  :config
  (consult-gh-embark-mode +1))
```

```emacs-lisp
(require 'consult-gh-embark)
(consult-gh-embark-mode +1)
```

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

### Create New File in Repository

Source: https://github.com/armindarvish/consult-gh/blob/main/_autodocs/api-reference-dired-browser.md

Creates a new file in the current directory. Prompts for file name and content, then commits and pushes the new file. Use this when pressing 'C' in a dired buffer.

```elisp
(consult-gh-dired-create-file)
```

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

### Configure Repository View Mode Keybindings

Source: https://github.com/armindarvish/consult-gh/blob/main/README.org

Sets custom keybindings for the repository view mode in consult-gh. This example binds 'C-c C-<return>' to open topics in the browser.

```emacs-lisp
(setq consult-gh--repo-view-mode-keybinding-alist
      '(("C-c C-<return>" . consult-gh-topics-open-in-browser)))
```

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

### Get Issue/PR Number from Candidate

Source: https://github.com/armindarvish/consult-gh/blob/main/_autodocs/types-and-data-structures.md

Retrieve the issue or pull request number from a candidate using `get-text-property`.

```elisp
;; Get issue/PR number
(get-text-property 0 :number candidate)
```

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

### Get Default Branch of a Repository

Source: https://github.com/armindarvish/consult-gh/blob/main/consult-gh.org

Retrieves the default branch name for a specified repository from the GitHub API.

```emacs-lisp
(defun consult-gh--repo-get-default-branch (repo)
  "Return REPO's default branch."
(consult-gh--json-to-hashtable
 (consult-gh--api-get-command-string (format "/repos/%s" repo))
 :default_branch))
```

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

### Build a GitHub Repository Candidate

Source: https://github.com/armindarvish/consult-gh/blob/main/_autodocs/types-and-data-structures.md

Programmatically create a candidate object with properties like :repo, :user, :title, :url, and :stars.

```elisp
(propertize "golang/go"
            :class "repo"
            :repo "golang/go"
            :user "golang"
            :title "The Go programming language"
            :url "https://github.com/golang/go"
            :stars 123456)
```

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

### Get Package Name from Repository

Source: https://github.com/armindarvish/consult-gh/blob/main/consult-gh.org

Extracts the package name from a repository string (e.g., 'consult-gh' from 'armindarvish/consult-gh').

```emacs-lisp
(defun consult-gh--get-package (repo)
  "Return the package name of REPO.

  \(e.g. “consult-gh” if REPO is “armindarvish/consult-gh”
)"
  (cadr (consult-gh--split-repo repo)))
```

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

### View Workflow Details

Source: https://github.com/armindarvish/consult-gh/blob/main/consult-gh.org

Opens a preview of a workflow, displaying runs, header, and YAML content. It can create a new buffer or reload an existing one.

```emacs-lisp
(let* ((topic (format "%s/actions/%s" repo id-or-name))
         (buffer (or buffer (get-buffer-create consult-gh-preview-buffer-name)))
         (runs (consult-gh--workflow-get-runs repo id-or-name))
         (runs-text (consult-gh--workflow-format-runs repo id-or-name runs topic))
         (header-text (consult-gh--workflow-format-header repo id-or-name runs topic))
         (last-run (car-safe runs))
         (ref (and (hash-table-p last-run)
                   (gethash :headBranch last-run)))
         (sha (and (hash-table-p last-run)
                   (gethash :headSha last-run)))
         (yaml-text (consult-gh--workflow-format-yaml repo id-or-name topic ref sha))))

    (add-text-properties 0 1 (list :repo repo :type "workflow" :view "workflow" :last-ref ref) topic)

    (with-current-buffer buffer
      (let ((inhibit-read-only t))
        (erase-buffer)
        (fundamental-mode)
        (when header-text
          (insert header-text)
          (save-excursion
          (when (eq consult-gh-workflow-preview-major-mode 'org-mode)
           (consult-gh--github-header-to-org buffer))))
        (when runs-text
          (insert runs-text))
        (when yaml-text
          (insert yaml-text))
        (consult-gh--format-view-buffer "workflow")
        (outline-hide-sublevels 1)
        (consult-gh-workflow-view-mode +1)
        (setq-local consult-gh--topic topic)
        (current-buffer))))
```

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

### View Commit Details

Source: https://github.com/armindarvish/consult-gh/blob/main/consult-gh.org

Opens a preview of a commit candidate. Parses the candidate to extract repository and commit SHA, then displays the commit in a buffer. Handles existing buffers by offering to switch, reload, or create a new one.

```emacs-lisp
(defun consult-gh--commit-view-action (cand)
  "Browse file tree of a commmit candidate, CAND.

  Query the user to select a file from the file tree of repo at commit.

  This is a wrapper function around `consult-gh-commit-browse-files'.
  To use this as the default action for commits,
  set `consult-gh-commit-action' to `consult-gh-commit-browse-files'."
    (consult-gh-commit-browse-files cand))
```

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

### Load consult-gh Package

Source: https://github.com/armindarvish/consult-gh/blob/main/_autodocs/README.md

Use this command to load the consult-gh package into your Emacs session. Ensure the package is installed.

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

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

### Browse Repository Files

Source: https://github.com/armindarvish/consult-gh/blob/main/_autodocs/README.md

Use this command to browse repository files interactively. Navigate with arrow keys, open files with RET, and use keys like C, D, R for file operations.

```emacs-lisp
M-x consult-gh-dired
# Select repository
# Navigate with arrow keys
# RET to open file
# C to create file
# D to delete file
# R to rename file
# q to quit
```

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

### Get Repository Branches

Source: https://github.com/armindarvish/consult-gh/blob/main/consult-gh.org

Retrieves a list of branches for a given repository from the GitHub API and converts them into a propertized list.

```emacs-lisp
(consult-gh--api-get-json (concat "repos/" repo "/branches"))
```

```emacs-lisp
(defun consult-gh--repo-get-branches-hashtable-to-list (table repo)
  "Convert TABLE with branches of REPO to a list of propertized text."
  (mapcar (lambda (item)
            (when (hash-table-p item)
              (let* ((name (gethash :name item))
                     (api-url (gethash :url (gethash :commit item)))
                     (sha (gethash :sha (gethash :commit item)))
                     (protected (gethash :protected item)))
                  (when (stringp name)
                    (propertize name
                               :repo repo
                               :ref name
                               :api-url api-url
                               :sha sha
                               :protected protected
                               :type "branch"
                               :class "branch")))))
          table))
```

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

### Consult Multi-source Integration

Source: https://github.com/armindarvish/consult-gh/blob/main/_autodocs/types-and-data-structures.md

Integrate Consult GH with `consult--multi` to create multi-source searching dashboards. Configure prompt, keymap, and preview key.

```elisp
;; Dashboard uses multiple sources
(consult--multi
  (mapcar #'consult-gh--make-source source-list)
  :prompt "Find GitHub item: "
  :keymap consult-gh--keymap
  :preview-key consult-gh-preview-key)
```

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

### Initialize GitHub Completion Fields

Source: https://github.com/armindarvish/consult-gh/blob/main/consult-gh.org

Asynchronously fetches lists of fields for a given repository and topic. It populates completion candidates for issues, pull requests, mentionable users, and branches. Optionally collects labels, assignees, milestones, and projects if the user has admin privileges.

```emacs-lisp
(defun consult-gh--completion-set-all-fields (&optional repo topic admin)
  "Make async process to get list of all fields of REPO in TOPIC.

  ADMIN, is a boolean, whether the current user has permission to write
  to REPO or not.

  TOPIC is a string with properties containing metadata and defalts to
  the buffer-local variable `consult-gh--topic'."

  (let*  ((type (get-text-property 0 :type topic)))
    ;; collect issues of repo for completion at point
    (consult-gh--completion-set-issues topic repo)
    ;; collect prs of repo for completion at point
    (consult-gh--completion-set-prs topic repo)
    ;; collect mentionable users for completion at point
    (consult-gh--completion-set-mentionable-users topic repo)
    ;; collect branches of the repo
    (consult-gh--completion-set-branches topic repo)
    ;; collect valid refs for completion at point
    (when (equal type "pr")
      (consult-gh--completion-set-pr-refs topic nil nil nil))

    (when (equal type "release")
      (consult-gh--completion-set-release-tags topic repo))

    (cond
     (admin
      ;; collect labels for completion at point
      (consult-gh--completion-set-valid-labels topic repo)
      ;; collect valid assignees for completion at point
      (consult-gh--completion-set-assignable-users topic repo)
      ;; collect valid milestones for completion at point
      (consult-gh--completion-set-valid-milestones topic repo)
      ;; collect valid projects for completion at point
      (consult-gh--completion-set-valid-projects topic repo))
     (t
      (add-text-properties 0 1 (list :valid-labels nil :assignable-users nil :valid-milestones nil :valid-projects nil) topic)))))

#+end_src
```

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

### Get Markers for Metadata

Source: https://github.com/armindarvish/consult-gh/blob/main/consult-gh.org

Retrieves specific markers based on the current `consult-gh-topic-major-mode`. Used for formatting metadata fields.

```emacs-lisp
(defun consult-gh-topics--markers-for-metadata ()
  "Get markers depending on `consult-gh-topic-major-mode'."
  (pcase consult-gh-topic-major-mode
    ('gfm-mode
     (list "# " "> "))
    ('markdown-mode
     (list "# " "> "))
    ('org-mode
     (list "#+" "#+"))
    (_
     (list "# " "> "))))
```

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

### Get Projects

Source: https://github.com/armindarvish/consult-gh/blob/main/consult-gh.org

Retrieves a list of projects (specifically ProjectsV2) associated with a given repository. It extracts the titles of these projects.

```emacs-lisp
(defun consult-gh--get-projects (repo)
  "Get a list of projects of REPO."
  (let* ((topic consult-gh--topic)
         (json (consult-gh--command-to-string "repo" "view" repo "--json" "projectsV2"))
         (table (and (stringp json) (consult-gh--json-to-hashtable json :projectsV2)))
         (nodes (and (hash-table-p table) (gethash :Nodes table)))
         (projects (and nodes (listp nodes) (mapcar
                                             (lambda (item) (gethash :title item))
                                             nodes))))
    (when (stringp topic)
      (add-text-properties 0 1 (list :valid-projects projects) topic)
      projects)))
```

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

### Open Repository in System Browser with Embark

Source: https://github.com/armindarvish/consult-gh/blob/main/_autodocs/api-reference-embark-actions.md

Opens the GitHub page of a selected repository in the system's default browser. This action is specifically for repository lists.

```elisp
(consult-gh-embark-open-repo-in-system-browser cand)
```

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

### Display Repository Image and Profile

Source: https://github.com/armindarvish/consult-gh/blob/main/consult-gh.org

Constructs the display string for a repository, including its image and profile text. Handles cases where the image or profile file may not exist.

```emacs-lisp
(let* ((image (create-image image-path nil nil :height (floor (* (frame-width) 1))))) 

      (concat (if (and (file-exists-p image-path) (display-images-p))
                  (concat (propertize " " 'display image) "\n") "")
              (if (file-exists-p profile-path) (with-temp-buffer (insert-file-contents profile-path)
                                                                 (goto-char (point-min))
                                                                 (read (current-buffer)))
                repo)))
```

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

### Get Labels

Source: https://github.com/armindarvish/consult-gh/blob/main/consult-gh.org

Fetches a list of labels available in a specified GitHub repository. The labels are returned as a list of strings.

```emacs-lisp
(defun consult-gh--get-labels (repo)
  "Get a list of labels in REPO."
  (let* ((topic consult-gh--topic)
         (json (consult-gh--command-to-string "repo" "view" repo "--json" "labels"))
         (table (and (stringp json) (consult-gh--json-to-hashtable json :labels)))
         (labels (and table (listp table) (mapcar (lambda (item) (gethash :name item)) table))))
    (when (stringp topic)
      (add-text-properties 0 1 (list :valid-labels labels) topic))
    labels))
```

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

### Verify Embark Integration

Source: https://github.com/armindarvish/consult-gh/blob/main/_autodocs/README.md

Test Embark integration by selecting a candidate and pressing the Embark keybinding (typically C-.). This confirms custom actions are available and working.

```emacs-lisp
C-.
```