#+title: Helm Wiki
# #+subtitle:  Release {{{version}}}
#+subtitle:  Release 3.6.2
#+author:    The Helm Developers
# #+date:      {{{modification-time}}}
#+language:  en

# #+texinfo: @insertcopying

* Table Of Contents                                                   :TOC_4:
- [[#requirements][Requirements]]
- [[#download][Download]]
- [[#installation-upgrade-and-configuration][Installation, Upgrade, and Configuration]]
  - [[#minimal-setup-using-straightel][Minimal setup using =straight.el=]]
  - [[#minimal-setup-using-source][Minimal setup using source]]
  - [[#minimal-setup-using-the-package-manager][Minimal setup using the Package Manager]]
- [[#introduction][Introduction]]
- [[#helm-completion-vs-emacs-completion][Helm Completion v.s. Emacs Completion]]
  - [[#helm-interaction-model][Helm interaction model]]
- [[#general-helm-commands][General Helm Commands]]
  - [[#yanking-text][Yanking text]]
-  [[#preconfigured-helm-commands][Preconfigured Helm Commands]]
- [[#helm-mode][Helm Mode]]
  - [[#customize-helm-mode][Customize helm-mode]]
    - [[#use-helm-mode-and-ido-mode][Use helm-mode and ido-mode]]
- [[#helm-with-other-emacs-extensions][Helm With Other Emacs Extensions]]
  - [[#linum-relative][linum-relative]]
- [[#helm-workflow-for-files-directories-and-buffers][Helm Workflow for Files, Directories and Buffers]]
- [[#quick-try-with-emacs-helmsh][Quick Try with =emacs-helm.sh=]]
- [[#how-to-report-helm-bugs][How to report Helm Bugs]]
  - [[#confirming-bugs][Confirming bugs]]
    - [[#emacs-helmsh][=emacs-helm.sh=]]
    - [[#emacs--q][=emacs -Q=]]
  - [[#reporting-bugs][Reporting bugs]]
    - [[#version-info][Version info]]
- [[#useful-links][Useful links]]
- [[#main-index][Main Index]]
- [[#key-index][Key Index]]
- [[#command-and-function-index][Command and Function Index]]
- [[#variable-index][Variable Index]]
- [[#footnotes][Footnotes]]

* Requirements

Helm 3.6.2 and later require

  - =Emacs= version >= 25.1
  - =emacs-async=[fn:xxx1]
  - =popup-el=[fn:xxx2]

# Helm require an =Emacs= version >= 25.1 starting from version 3.6.2.
# Helm uses few dependencies, actually only  (mandatory) and
# popup (facultative) but if you install from
# Melpa[fn:xxx3] you should not care of this.

* Download

- Home Page ::   https://github.com/emacs-helm/helm

- Git Url ::

  https://github.com/emacs-helm/helm.git

  git@github.com:emacs-helm/helm.git

- Tagged Releases :: https://github.com/emacs-helm/helm/tags

* Installation, Upgrade, and Configuration

# 1. [[*Minimal setup using =straight.el=]]

# 2. [[*Minimal setup using source]]

# 3. [[*Minimal setup using the Package Manager]]

** Minimal setup using =straight.el=

=straight.el=[fn:xxx3]

Add this to your init file,

#+begin_src emacs-lisp
 (straight-use-package 'helm)
#+end_src

or

# #+begin_src emacs-lisp
#  (use-package helm
#	      :straight t
#	      :config
#	      [...])
# #+end_src

#+begin_src emacs-lisp
  (use-package helm :straight t)
#+end_src

For further information, see =straight.el='s user manual.

To upgrade =helm=, do {{{kbd(M-x straight-pull-package)}}} and restart
Emacs.  =straight.el= will rebuild helm for you.

** Minimal setup using source

# This the best alternative to the standard Emacs package manager with
# installation from source (see below).

# This is the safest way to install Helm.

1. Install the pre-requisites

   Install =emacs-async=[fn:xxx1] and =popup-el=[fn:xxx2].  Ensure that they
   are available in ~load-path~.

2. Download, compile and install the sources

  If you are using =git=,

     #+begin_src sh
       git clone https://github.com/emacs-helm/helm
       cd helm
       make
       sudo make install
     #+end_src

  If you have a tarball[fn:xxx4],

    #+begin_src sh
      wget https://github.com/emacs-helm/helm/archive/refs/tags/v3.7.1.tar.gz
      tar zxvf v3.7.1.tar.gz
      cd helm-3.7.1/
      make
      sudo make install
    #+end_src

Above steps assume that you have installed =emacs-async= is in a
standard location.  If this is not the case, you need to tell =make=
program where it is available using =EMACSLOADPATH=[fn:xxx5].

     #+begin_src sh
       git clone https://github.com/emacs-helm/helm
       cd helm
       EMACSLOADPATH="/path/to/emacs-async:" make
       make
       sudo make install
     #+end_src

Above steps

- installs =helm= in =/usr/local/share/emacs/site-lisp/helm/=

- creates an executable called =/usr/local/bin/helm=.  This file is in
  fact a symbolic link to to the script =emacs-helm.sh=.

  #+cindex: emacs-helm.sh

If you want to install =helm= in a path other than =/usr/local/=, pass
that target path through a =PREFIX= variable.

Add the one of the following to your init file,

#+begin_src emacs-lisp
  (add-to-list 'load-path "/path/to/helm/directory")
  (require 'helm-config)
#+end_src

or

#+begin_src emacs-lisp
  (add-to-list 'load-path "/path/to/helm/directory")
  (use-package helm :config (require 'helm-config))
#+end_src

and restart Emacs.

The library =helm-config= loads =helm-autoloads.el=.  This is
essential for having a working install of =helm=.

# *Note*: make install will NOT work on Windows system, but you can move
# your helm directory to your ~load-path~ e.g. /site-lisp and run =make=
# there.

** Minimal setup using the Package Manager

Helm is available on MELPA.[fn:xxx6]

Release version of Helm is available in the stable repository while
development version is available in the other repo.

Assuming that you have setup ~package-archives~ to include the MELPA,
you can install Helm with {{{kbd(M-x package-install RET helm RET)}}}.

To upgrade =Helm=, use ~helm-list-elisp-packages~.  This command is
the Helm equivalent of Emacs' =list-packages=.  Using
~helm-list-elisp-packages~, ensures that =helm= is compiled in a clean
environment.[fn:xxx7]

# Helm upgrades from MELPA encountered errors because of the way the
# Emacs package manager fetches and compiles updates for existing
# packages.

# To get around these errors, Helm has =emacs-async=[fn:xxx1] as a
# dependency. =emacs-async= forces compilation in a clean environment,
# which resolves the compilation errors.

# When some changes are made in Helm-core and those changes are used in
# Helm, package.el may install Helm before Helm-core which may create
# errors depending on changes on Helm-core e.g. New macro, renaming
# function or macro etc...  In this case you will have a better time
# uninstalling all (Helm+Helm-core), restarting Emacs and reinstalling
# Helm.  Installing from source doesn't suffer from this problem.

# *Note*: always restart Emacs after reinstalling Helm (or other
# packages) for updates to take effect.

# ** Upgrading

# The only thing you have to do is to upgrade from package manager.

# Helm comes with convenient interface to package.el, see
# ~helm-list-elisp-packages-no-fetch~ and ~helm-list-elisp-packages~.

# Use ~helm-list-elisp-packages~ to upgrade Helm.  If you use
# ~list-packages~ to upgrade, you may run in to issues either at install
# time or run time.[fn:xxx8]

# * Upgrade or recompile

# ** Melpa

# *** Upgrade

# *** COMMENT Recompile

# To recompile Helm (or whatever packages), always recompile from a
# clean environment, that is from outside you current Emacs, for this
# use ~helm-list-elisp-packages-no-fetch~, go to installed packages with
# ~M-I~ and use the recompile package action, from Lisp you can use
# directly ~async-byte-recompile-directory~, if you installed from
# source use make. And then RESTART Emacs.

# ** Straight

* COMMENT Configure

# For further configuration like changing bindings in the ~helm-map~ you
# will likely want to use a delayed method like ~with-eval-after-load~
# or =use-package= to avoid loading all of Helm at startup.

As example you can have a look at the maintainer helm config[fn:xxx8].

To setup specific variables from the helm session you are in, use
{{{kbd(C-h c)}}}.

To enable helm completion everywhere in Emacs add this to your init
file.

#+begin_src emacs-lisp
  (helm-mode 1)
#+end_src

* Introduction

People often think helm is just something like ido([[info:Ido]]) but
displaying completion in a vertical layout instead of an horizontal
one, it is not, helm is much more powerful than that.

- Helm is able to complete multiple lists dispatched in different
  sources against a pattern.

- Helm allows executing an unlimited number of actions on candidates.

- Helm allows marking candidates to execute chosen action against this
  set of candidates.

- Helm can display its completion buffer in different window layouts
  and in separate frame.

Helm is divided in two distinct categories of commands,

#+cindex: helm native commands
#+cindex: helmized commands

- *helm natives commands* :: these commands are a fresh implementation
  of an existing Emacs command and enhance them in useful ways.

- *helmized commands* :: these Emacs native commands modified by
  helm-mode to provide helm completion and only that.

When both are provided e.g ~switch-to-buffer~ vs ~helm-buffers-list~
you will prefer the native helm commands generally more featured (more
than one action, allows marking candidates, better display etc...).

* Helm Completion v.s. Emacs Completion

Differences between the two often trip up new users.

Emacs completion is based on the *minibuffer*. Helm completion is
based on the *completion window*.[fn:xxx9]  [fn:xxx10] [fn:xxx11]

In standard Emacs, interactivity happens in the /minibuffer/.

- Typing new characters filters candidates in the minibuffer.
  {{{kbd(<tab>)}}} may try to complete the typed characters with a
  valid candidate.

- Hitting {{{kbd(RET)}}} selects the current candidate from the minibuffer.

In Helm, interactivity happens in the /completion window/, not the
minibuffer

- Typing new characters filters candidates in the completion window.
  Keep typing until the desired candidate is highlighted, or navigate
  to it using {{{kbd(C-n)}}}.

- Hitting {{{kbd(RET)}}} selects the currently highlighted item in the
  completion window.

** Helm interaction model

Helm's interactivity makes the {{{kbd(<tab>)}}} key redundant for
completion because the selection candidates are already made visible
in the Helm completion window. So, *tab completion is not
supported*. In Helm, {{{kbd(<tab>)}}} is used to view available
*actions* to be taken on a candidate.

Because the {{{kbd(<tab>)}}} key is so ingrained in the muscle memory of
long-time Emacs users, transition to Helm's interactive model
requires:

- A conscious visual adjustment to look at the completion window, and

- A conscious mental adjustment to avoid using the {{{kbd(<tab>)}}}
  key for completion and go straight to {{{kbd(RET)}}} key to select a
  candidate. Helm's approach to completion provides better visual
  cues, takes fewer keystrokes, and is much faster.

* General Helm Commands

#+CAPTION: A typical ~helm-M-x~ with =emacs-helm.sh=
#+ATTR_HTML: :width 800
#+ATTR_ORG: :width 800
[[./helm-M-x.png]]

Helm's functionality needs only a few general key bindings as shown
below. These are also documented in the mode line.

# Marking

 # helm-mark-all
 # helm-next-visible-mark
 # helm-prev-visible-mark
 # helm-toggle-all-marks
 # helm-toggle-visible-mark
 # helm-toggle-visible-mark-backward
 #
 # helm-unmark-all

# Action

 # helm-execute-persistent-action
 # helm-follow-action-backward
 # helm-follow-action-forward
 # helm-select-action

# - {{{kbd(C-c C-e)}}} (~org-export~) ::

- {{{kbd(<tab>)}}} or {{{kbd(C-i)}}} (~helm-select-action~) :: lists available actions

- {{{kbd(C-j)}}} or {{{kbd(C-z)}}} (~helm-execute-persistent-action~) :: invokes the persistent action

- {{{kbd(M-SPC)}}} (~helm-toggle-visible-mark-backward~)  or {{{kbd(C-SPC)}}} (~helm-toggle-visible-mark-forward~) or {{{kbd(C-@)}}} (~helm-toggle-visible-mark~) :: marks a candidate

- {{{kbd(C-h m)}}} (~helm-help~) :: displays the embeded help in an org buffer without quitting
  helm session.

- {{{kbd(RET)}}}   :: runs the first action of action list

** Yanking text

Yank symbol at point from ~helm-current-buffer~ (i.e. buffer where a
helm command was invoked):

# {{{kbd(M-n)}}} copies symbol at point to minibuffer

# {{{kbd(C-w)}}} appends word next to point to the minibuffer and advance to next
# word, hitting {{{kbd(C-_)}}} undo last insertion and rewind yank point in
# ~helm-current-buffer~

- {{{kbd(C-w)}}} (~helm-yank-text-at-point~) :: Append word next to
  point to the minibuffer and advance to next word

   (helm-yank-text-at-point ARG)

   Yank text at point in `helm-current-buffer' into minibuffer.

- {{{kbd(C-_)}}} (~helm-undo-yank-text-at-point~) :: Undo last
  insertion and rewind yank point in ~helm-current-buffer~

   Undo last entry added by `helm-yank-text-at-point'.

*  Preconfigured Helm Commands

Invoke {{{kbd(M-x helm-M-x RET)}}} and type =helm= to discover Helm
commands.  The =Menu Bar -> Helm= menu item is another way to discover
helm commands.

- ~helm-command-prefix-key~ ::

  #+vindex: helm-command-prefix-key

  *Standard Value*: "C-x c"

  The key ‘helm-command-prefix’ is bound to in the global map.

- ~helm-minibuffer-history-key~ ::

  #+vindex: helm-minibuffer-history-key

  *Standard Value*: "C-r"

  The key ‘helm-minibuffer-history’ is bound to in minibuffer local maps.

# #+vindex: helm-command-prefix-key
~helm-command-prefix-key~ (default value {{{kbd(C-x c)}}}) is the
prefix for the preconfigured helm menu.

~helm-command-prefix-key~ followed by any regular Emacs key invokes
the Helm version of the same command.

For example,

- {{{kbd(C-x c M-x)}}} runs the command ~helm-M-x~, which is the helm
  version of {{{kbd(M-x)}}} (~execute-extended-command~).

- {{{kbd(C-x c C-x C-f)}}} runs the command ~helm-find-files~, which
  is the helm version of {{{kbd(C-x C-f)}}} (~find-file~).

To run the helm version of a command with a key binding, but without
also typing {{{kbd(C-x c)}}}) (~helm-command-prefix-key~), add the
following to your init file.

#+begin_src emacs-lisp
  (global-set-key (kbd "M-x") 'helm-M-x)
#+end_src

* COMMENT Show Helm Commands

- {{{kbd(C-h m)}}} (~helm-help~) shows Helm commands and currently
  active key bindings.

# * Browse Other Tools

# - Invoke {{{kbd(M-x)}}}, then type "helm" to browse other Helm tools.

* Helm Mode

# Toggle generic helm completion.

# If called interactively, toggle ‘Helm mode’.  If the prefix
# argument is positive, enable the mode, and if it is zero or
# negative, disable the mode.

# If called from Lisp, toggle the mode if ARG is ‘toggle’.  Enable
# the mode if ARG is nil, omitted, or is a positive number.
# Disable the mode if ARG is a negative number.

# The mode’s hook is called both when the mode is enabled and when
# it is disabled.

# All functions in Emacs that use ‘completing-read’,
# ‘read-file-name’, ‘completion-in-region’ and friends will use helm
# interface when this mode is turned on.

# However you can modify this behavior for functions of your choice
# with ‘helm-completing-read-handlers-alist’.

# Called with a positive arg, turn on unconditionally, with a
# negative arg turn off.
# You can toggle it with M-x ‘helm-mode’.

# About ‘ido-mode’:
# DO NOT enable ‘ido-everywhere’ when using ‘helm-mode’.  Instead of
# using ‘ido-mode’, add the commands where you want to use ido to
# ‘helm-completing-read-handlers-alist’ with ‘ido’ as value.

~helm-mode~ enables Helm completion globally for any Emacs command
using ~completing-read~ or ~read-file-name~.

~helm-mode~ completes with ~completion-at-point~ and implements
~completion-in-region-function~ for ~completing-read-multiple~ for
Emacs 24.4 and later.

Helm provides generic functions for completions to replace
tab-completion in Emacs with no loss of functionality. To use Helm's
generic functions, first set them in your init file, e.g.:

#+begin_src emacs-lisp
  (global-set-key (kbd "M-x") #'helm-M-x)
  (global-set-key (kbd "C-x r b") #'helm-filtered-bookmarks)
  (global-set-key (kbd "C-x C-f") #'helm-find-files)
#+end_src

Then enable ~helm-mode~ with:

#+begin_src emacs-lisp
  (helm-mode 1)
#+end_src

Or, enable ~helm-mode~ interactively with {{{kbd(M-x helm-mode)}}}.

- ~helm-mode~ ::

  #+vindex: helm-mode

  (helm-mode &optional ARG)

  Toggle generic helm completion.

  If called interactively, toggle `Helm mode'.  If the prefix
  argument is positive, enable the mode, and if it is zero or
  negative, disable the mode.

  If called from Lisp, toggle the mode if ARG is `toggle'.  Enable
  the mode if ARG is nil, omitted, or is a positive number.
  Disable the mode if ARG is a negative number.

  The mode's hook is called both when the mode is enabled and when
  it is disabled.

  All functions in Emacs that use `completing-read',
  `read-file-name', `completion-in-region' and friends will use helm
  interface when this mode is turned on.

  However you can modify this behavior for functions of your choice
  with `helm-completing-read-handlers-alist'.

  Called with a positive arg, turn on unconditionally, with a
  negative arg turn off.
  You can toggle it with M-x `helm-mode'.

  About `ido-mode':
  DO NOT enable `ido-everywhere' when using `helm-mode'.  Instead of
  using `ido-mode', add the commands where you want to use ido to
  `helm-completing-read-handlers-alist' with `ido' as value.

  Note: This mode is incompatible with Emacs23.

** Customize helm-mode

- ~helm-completing-read-handlers-alist~ ::

  #+vindex: helm-completing-read-handlers-alist

  Completing read functions for specific Emacs commands.

  By default ‘helm-mode’ use ‘helm-completing-read-default-handler’ to
  provide helm completion in each ‘completing-read’ or ‘read-file-name’
  found, but other functions can be specified here for specific
  commands. This also allows disabling helm completion for some commands
  when needed.

  Each entry is a cons cell like (EMACS_COMMAND . COMPLETING-READ_HANDLER)
  where key and value are symbols.

  Each key is an Emacs command that use originaly ‘completing-read’.

  Each value maybe a helm function that takes same arguments as
  ‘completing-read’ plus NAME and BUFFER, where NAME is the name of the new
  helm source and BUFFER the name of the buffer we will use, but it can
  be also a function not using helm, in this case the function should
  take the same args as ‘completing-read’ and not be prefixed by "helm-".

  ‘helm’ will use the name of the command calling ‘completing-read’ as
  NAME and BUFFER will be computed as well with NAME but prefixed with
  "*helm-mode-".

  This function prefix name must start by "helm-" when it uses helm,
  otherwise ‘helm’ assumes the function is not a helm function and
  expects the same args as ‘completing-read’, this allows you to define a
  handler not using helm completion.

  Example:

      (defun foo/test ()
	(interactive)
	(message "%S" (completing-read "test: " ’(a b c d e))))

      (defun helm-foo/test-completing-read-handler (prompt collection
						    predicate require-match
						    initial-input hist def
						    inherit-input-method
						    name buffer)
	(helm-comp-read prompt collection :marked-candidates t
					  :name name
					  :buffer buffer))

      (add-to-list ’helm-completing-read-handlers-alist
		   ’(foo/test . helm-foo/test-completing-read-handler))

  We want here to make the regular ‘completing-read’ in ‘foo/test’
  return a list of candidate(s) instead of a single candidate.

  Note that this function will be reused for ALL the ‘completing-read’
  of this command, so it should handle all cases. E.g.,
  if first ‘completing-read’ completes against symbols and
  second ‘completing-read’ should handle only buffer,
  your specialized function should handle both.

  If the value of an entry is nil completion will fall back to
  Emacs vanilla behaviour.
  Example:

  If you want to disable helm completion for ‘describe-function’, use:

      (describe-function . nil)

  Ido is also supported, you can use ‘ido-completing-read’ and
  ‘ido-read-file-name’ as value of an entry or just ’ido.
  Example:
  Enable ido completion for ‘find-file’:

      (find-file . ido)

  same as

      (find-file . ido-read-file-name)

  Note that you don’t need to enable ‘ido-mode’ for this to work, see
  ‘helm-mode’ documentation.

# #+vindex: helm-completing-read-handlers-alist
To customize the completion interface or disable completion for
specific commands in ~helm-mode~, edit
~helm-completing-read-handlers-alist~. See {{{kbd(C-h v)}}}
~helm-completing-read-handlers-alist~ for details.

*** Use helm-mode and ido-mode

To use
[[https://www.gnu.org/software/emacs/manual/html_mono/ido.html][Ido]]
for some commands and Helm for others, do not enable
~ido-mode~. Instead, customize ~helm-completing-read-handlers-alist~
to specify which command uses Ido.

For example, suppose we want ~find-file-read-only~ to use Ido and
~find-file~ to use Helm. Then:

1. In your init file, turn on ~helm-mode~.

2. In the ~helm-mode~ customize group, add a key to
   ~helm-completing-read-handlers-alist~ for ~find-file-read-only~
   with value =ido=, i.e.

#+begin_src emacs-lisp
  (find-file-read-only . ido)
#+end_src

With ~helm-mode~ active, to use Emacs default completion instead of
either Helm or Ido, use ~nil~ for the key value:

#+begin_src emacs-lisp
  (find-alternate-file . nil)
#+end_src

* COMMENT Other Useful Extensions

MELPA and other repositories have many useful extensions, some of
which are redundant as Helm already provides them. Review if they
already exist as part of the default Helm package before downloading
new extensions.

* Helm With Other Emacs Extensions

** linum-relative

~(helm-linum-relative-mode 1)~ enables ~linum-relative~ in Helm. Helm
buffers then display line numbered candidates before and after the
current candidate (highlighted line). {{{kbd(C-x <n>)}}} jumps to =n= lines
before, before, and {{{kbd(C-c <n>)}}} jumps to =n= lines after, the current
candidate.

* Helm Workflow for Files, Directories and Buffers

# The new Helm workflow uses fewer buffers. Whereas the old workflow
# opened many Dired buffers stacked in the workspace, the new approach
# uses virtual Dired buffers without cluttering the buffer list with
# many Dired buffers.  The decluttering of buffers also helps with
# running ~helm-locate~ without conflicts; there's also less need to
# resort to other workarounds, such as running ~helm-multi-files~.

# The new approach uses ~helm-find-files~ as the starting point, never
# opens Dired buffers yet provides easy access to common Helm commands,
# such as =grep=, =locate=, =find=, etc. These Helm commands, moreover,
# are not limited to the current directory because Helm now allows
# marking files in other directories before running the commands.

Other quick jumping off features of ~helm-find-files~:

- {{{kbd(C-x C-d)}}} (~helm-browse-project~) shows buffers and files in the
  project.

- {{{kbd(C-c C-d)}}} with prefix argument shows files in this directory and its
  subdirectories recursively.

When using =helm-ls-git=[fn:xxx12] and =helm-ls-hg=[fn:xxx13] , files under
version control have a corresponding backend indicator.

- {{{kbd(C-x C-b)}}} to switch back to the resumed Helm sources.

- {{{kbd(M-p)}}} to access history of ~helm-find-files~

- {{{kbd(C-c h)}}} to access the full history of files (~file-name-history~)

- {{{kbd(C-x C-f)}}} switches back to ~helm-find-files~

* Quick Try with =emacs-helm.sh=

#+cindex: emacs-helm.sh

To try Helm with a default configurations in a minimal Emacs, run the
provided =emacs-helm.sh= script in Helm's installation directory.  If
installed through the Emacs package manager,

#+begin_src sh
  ~/.emacs.d/elpa/helm-<VERSION>/emacs-helm.sh
#+end_src

=emacs-helm.sh= should also be used when
[[https://github.com/emacs-helm/helm/wiki/Bugs][reporting bugs]].

*Note*: If you have installed from Melpa, for convenience, consider
creating a symlink of =emacs-helm.sh= to e.g =~/bin=, if you have
installed from source (make && sudo make install) a symlink named
=helm= have already been created.

*Note*: For people using a non standard Elpa directory emacs-helm.sh may
fail because it doesn't find its dependency (emacs-async), here's how
you can do:

#+begin_src sh
  cd /your/path/to/helm
  make # If not already done.
  EMACSLOADPATH="../emacs-async:" ./emacs-helm.sh
#+end_src

But normally =emacs-helm.sh= should work out of the box with
installations of emacs-async= done with package.el, straight.el or from
source with the Makefile.

* How to report Helm Bugs

** Confirming bugs

To confirm that a bug is, in fact, a Helm problem, it is important to
/replicate the behavior with a minimal Emacs configuration/. This
precludes the possibility that the bug is caused by factors outside of
Helm.

The easiest and recommended way to do so is through the
=emacs-helm.sh= script.

*** =emacs-helm.sh=

If your system supports it, you should run the =emacs-helm.sh= script
to start an Emacs instance with minimal, Helm-specific configuration.

This is useful for debugging, and easier than starting Emacs with
=emacs -Q= and configuring Helm from scratch.

If Helm is installed via MELPA, the =emacs-helm.sh= script should be
located at =~/.emacs.d/elpa/helm-<version>/emacs-helm.sh=.

Of course you have to cd to your helm directory and run the script
from there, an alternative is symlinking it to somewhere in your
=PATH= e.g. "~/bin" (See note at bottom for those that have installed
from source with =make=).

You can use the -h argument for help:

    : $ helm -h
    : Usage: helm [-P} Emacs path [-h} help [--] EMACS ARGS

If your emacs binary is not in a standard place i.e. "emacs", you can
specify the path with "-P".

~Note~: If you have installed Helm from Git and used =make && sudo
make install= you can run directly =helm= at command line from any
place i.e. no need to cd to helm directory.

*** =emacs -Q=

If you cannot run the =emacs-helm.sh= script, be sure to reproduce the
problem with =emacs -Q=, then installing Helm as described in the
Install section.

** Reporting bugs

To report a bug, [[https://github.com/emacs-helm/helm/issues][open an
issue]]. Be sure that you've confirmed the bug as described in the
previous section, and include relevant information for the maintainer
to identify the bug.

*** Version info

When reporting bugs, it is important to include the Helm version
number, which can be found in the
[[https://github.com/emacs-helm/helm/blob/master/helm-pkg.el][helm-pkg.el]]
file.

* Useful links

- [[https://github.com/emacs-helm/helm][Helm on GitHub]]

- [[http://tuhdo.github.io/helm-intro.html][Tuhdo's Helm tutorial]]

- [[https://groups.google.com/g/emacs-helm][Helm mailing list]]

# gmane.emacs.helm.user
# news://news.gwene.org:119/gmane.emacs.helm.user

# - [[http://dir.gmane.org/gmane.emacs.helm.user][Helm Gmane]] (=gmane.emacs.helm.user=)

* COMMENT Contributing to the Wiki

1. Prefer using [[http://orgmode.org/][Org mode]] for Wiki pages.

2. Install the [[https://github.com/snosov1/toc-org][toc-org]] package
   to automatically generate tables of contents.

3. Edit the Wiki.

4. Before saving, run ~toc-org-insert-toc~.

   - Consider adding something like the following to
     ~before-save-hook~ to do this automatically:

#+begin_src emacs-lisp
  (defun *-org-insert-toc ()
    "Create table of contents (TOC) if current buffer is in
  `org-mode'."
    (when (= major-mode 'org-mode)
      toc-org-insert-toc))
#+end_src

* Main Index
:PROPERTIES:
:INDEX:    cp
:DESCRIPTION: An index of Helm's concepts and features.
:END:

* Key Index
:PROPERTIES:
:DESCRIPTION: Key bindings and where they are described.
:INDEX:    ky
:END:

* Command and Function Index
:PROPERTIES:
:DESCRIPTION: Command names and some internal functions.
:INDEX:    fn
:END:

* Variable Index
:PROPERTIES:
:DESCRIPTION: Variables mentioned in the manual.
:INDEX:    vr
:END:

This is not a complete index of variables and faces, only the ones
that are mentioned in the manual.  For a more complete list, use
{{{kbd(M-x org-customize)}}} and then click yourself through the tree.

* Export Setup                                                          :noexport:

#+setupfile: doc-setup.org
# #+options: H:4

#+export_file_name: helm-manual-1.texi

#+texinfo_dir_category: Emacs Add-ons
#+texinfo_dir_title: Helm Wiki: (helm-manual-1)
#+texinfo_dir_desc: Helm Wiki

* Footnotes

[fn:xxx1] [[https://github.com/jwiegley/emacs-async][emacs-async]]

[fn:xxx2] [[https://github.com/auto-complete/popup-el][popup-el]]

[fn:xxx3] https://github.com/raxod502/straight.el

[fn:xxx4]  https://github.com/emacs-helm/helm/releases

[fn:xxx5] Don't forget the final =:= to use an absolute path (like
=/home/you/foo/bar:=) instead of an abbreviated path like
(=~/foo/bar:=), specify =EMACSLOADPATH=.

[fn:xxx6] https://melpa.org

[fn:xxx7] Helm uses async package to compile itself from Melpa.  Ensure
that ~async-bytecomp-package-mode~ is enabled by default.  If this
isn't so, add helm to ~async-bytecomp-allowed-packages~.

[fn:xxx8] https://raw.githubusercontent.com/thierryvolpiatto/emacs-config/main/init-helm.el

[fn:xxx9] [[https://github.com/emacs-helm/helm/issues/495][Different way of invoking commands]]

[fn:xxx10] [[https://groups.google.com/g/emacs-helm/c/zaBbg2tFAuM][Finding files]]

[fn:xxx11] [[https://github.com/emacs-helm/helm/issues/222][Lack of tab completion]]

[fn:xxx12][[https://github.com/emacs-helm/helm-ls-git][helm-ls-git]]

[fn:xxx13] [[https://github.com/emacs-helm/helm-ls-hg][helm-ls-hg]]

[fn:xxx14][[http://melpa.org/#/helm][MELPA]]


[fn:xxx15] [[http://stable.melpa.org/#/helm][MELPA Stable]]

[fn:xxx16] https://github.com/emacs-helm/helm/tags

[fn:xxx17] [[http://melpa.org/#/helm][Melpa ]]

[fn:xxx18] helm-core have a new macro foo and helm use now
this macro, ~list-packages~ will try to install and compile first helm
and then helm-core resulting in an error like =void function foo...=.


#+STARTUP: inlineimages
#+EXCLUDE_TAGS: TOC_4

# (info (org-texinfo-export-to-info))
