;;; helm-help.el --- Help messages for Helm. -*- lexical-binding: t -*-
|
|
;; Copyright (C) 2012 ~ 2018 Thierry Volpiatto <thierry.volpiatto@gmail.com>
|
|
;; This program is free software; you can redistribute it and/or modify
|
;; it under the terms of the GNU General Public License as published by
|
;; the Free Software Foundation, either version 3 of the License, or
|
;; (at your option) any later version.
|
|
;; This program is distributed in the hope that it will be useful,
|
;; but WITHOUT ANY WARRANTY; without even the implied warranty of
|
;; MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the
|
;; GNU General Public License for more details.
|
|
;; You should have received a copy of the GNU General Public License
|
;; along with this program. If not, see <http://www.gnu.org/licenses/>.
|
|
;;; Code:
|
(require 'helm)
|
|
(defvar helm-org-headings--nofilename)
|
(declare-function helm-source-org-headings-for-files "helm-org.el")
|
|
|
(defgroup helm-help nil
|
"Embedded help for `helm'."
|
:group 'helm)
|
|
(defface helm-helper
|
'((t :inherit helm-header))
|
"Face for Helm help string in minibuffer."
|
:group 'helm-help)
|
|
(defvar helm-help--string-list '(helm-help-message
|
helm-buffer-help-message
|
helm-ff-help-message
|
helm-read-file-name-help-message
|
helm-generic-file-help-message
|
helm-grep-help-message
|
helm-pdfgrep-help-message
|
helm-etags-help-message
|
helm-ucs-help-message
|
helm-bookmark-help-message
|
helm-esh-help-message
|
helm-buffers-ido-virtual-help-message
|
helm-moccur-help-message
|
helm-top-help-message
|
helm-el-package-help-message
|
helm-M-x-help-message
|
helm-imenu-help-message
|
helm-colors-help-message
|
helm-semantic-help-message
|
helm-kmacro-help-message))
|
|
(defvar helm-documentation-buffer-name "*helm documentation*")
|
|
;;;###autoload
|
(defun helm-documentation ()
|
"Preconfigured Helm for Helm documentation.
|
With a prefix arg refresh the documentation.
|
|
Find here the documentation of all documented sources."
|
(interactive)
|
(require 'helm-org)
|
(with-current-buffer (get-buffer-create helm-documentation-buffer-name)
|
(let ((inhibit-read-only t))
|
(erase-buffer)
|
(cl-loop for elm in helm-help--string-list
|
for str = (helm-interpret-value elm)
|
do (insert (substitute-command-keys str) "\n\n"))
|
(org-mode))
|
(setq buffer-read-only t)
|
(view-mode))
|
(let ((helm-org-headings--nofilename t))
|
(helm :sources (helm-source-org-headings-for-files
|
(list (get-buffer helm-documentation-buffer-name)))
|
:candidate-number-limit 99999
|
:buffer "*helm doc*")))
|
|
;;; Local help messages.
|
|
;;; `helm-buffer-list' help
|
;;
|
;;
|
(defvar helm-buffer-help-message
|
"* Helm Buffer
|
|
** Tips
|
|
*** Completion
|
|
**** Major-mode
|
|
You can enter a partial major-mode name (e.g. lisp, sh) to narrow down buffers.
|
To specify the major-mode, prefix it with \"*\" e.g. \"*lisp\".
|
|
If you want to match all buffers but the ones with a specific major-mode
|
\(negation), prefix the major-mode with \"!\" e.g. \"*!lisp\".
|
|
If you want to specify more than one major-mode, separate them with \",\",
|
e.g. \"*!lisp,!sh,!fun\" lists all buffers but the ones in lisp-mode, sh-mode
|
and fundamental-mode.
|
|
Then enter a space followed by a pattern to narrow down to buffers matching this
|
pattern.
|
|
**** Search inside buffers
|
|
If you enter a space and a pattern prefixed by \"@\", Helm searches for text
|
matching this pattern \*inside* the buffer (i.e. not in the name of the buffer).
|
|
If you enter a pattern prefixed with an escaped \"@\", Helm searches for a
|
buffer matching \"@pattern\" but does not search inside.
|
|
**** Search by directory name
|
|
If you prefix the pattern with \"/\", Helm matches over the directory names
|
of the buffers.
|
|
This feature can be used to narrow down the search to one directory while
|
subsequent strings entered after a space match over the buffer name only.
|
|
Note that negation is not supported for matching on buffer filename.
|
|
Starting from Helm v1.6.8, you can specify more than one directory.
|
|
**** Fuzzy matching
|
|
`helm-buffers-fuzzy-matching' turns on fuzzy matching on buffer names, but not
|
on directory names or major modes. A pattern starting with \"^\" disables fuzzy
|
matching and matches by exact regexp.
|
|
**** Examples
|
|
With the following pattern
|
|
\"*lisp ^helm @moc\"
|
|
Helm narrows down the list by selecting only the buffers that are in lisp mode,
|
start with \"helm\" and which content matches \"moc\".
|
|
Without the \"@\"
|
|
\"*lisp ^helm moc\"
|
|
Helm looks for lisp mode buffers starting with \"helm\" and containing \"moc\"
|
in their name.
|
|
With this other pattern
|
|
\"*!lisp !helm\"
|
|
Helm narrows down to buffers that are not in \"lisp\" mode and that do not match
|
\"helm\".
|
|
With this last pattern
|
|
/helm/ w3
|
|
Helm narrows down to buffers that are in any \"helm\" subdirectory and
|
matching \"w3\".
|
|
*** Creating buffers
|
|
When creating a new buffer, use `\\[universal-argument]' to choose a mode from a
|
list. This list is customizable, see `helm-buffers-favorite-modes'.
|
|
*** Killing buffers
|
|
You can kill buffers either one by one or all the marked buffers at once.
|
|
One kill-buffer command leaves Helm while the other is persistent. Run the
|
persistent kill-buffer command either with the regular
|
`helm-execute-persistent-action' called with a prefix argument (`\\[universal-argument] \\<helm-map>\\[helm-execute-persistent-action]')
|
or with its specific command `helm-buffer-run-kill-persistent'. See the
|
bindings below.
|
|
*** Switching to buffers
|
|
To switch to a buffer, press RET, to switch to a buffer in another window, select this buffer
|
and press \\<helm-buffer-map>\\[helm-buffer-switch-other-window], when called with a prefix arg
|
the buffer will be displayed vertically in other window.
|
If you mark more than one buffer, the marked buffers will be displayed in different windows.
|
|
*** Meaning of colors and prefixes for buffers
|
|
Remote buffers are prefixed with '@'.
|
Red => Buffer's file was modified on disk by an external process.
|
Indianred2 => Buffer exists but its file has been deleted.
|
Orange => Buffer is modified and not saved to disk.
|
Italic => A non-file buffer.
|
Yellow => Tramp archive buffer.
|
|
** Commands
|
\\<helm-buffer-map>
|
\\[helm-buffer-run-zgrep]\t\tGrep Buffer(s) works as zgrep too (`\\[universal-argument]' to grep all buffers but non-file buffers).
|
\\[helm-buffers-run-multi-occur]\t\tMulti-Occur buffer or marked buffers (`\\[universal-argument]' to toggle force-searching current-buffer).
|
\\[helm-buffer-switch-other-window]\t\tSwitch to other window.
|
\\[helm-buffer-switch-other-frame]\t\tSwitch to other frame.
|
\\[helm-buffers-run-browse-project]\t\tBrowse project from buffer.
|
\\[helm-buffer-run-query-replace-regexp]\t\tQuery-replace-regexp in marked buffers.
|
\\[helm-buffer-run-query-replace]\t\tQuery-replace in marked buffers.
|
\\[helm-buffer-run-ediff]\t\tEdiff current buffer with candidate. With two marked buffers, ediff those buffers.
|
\\[helm-buffer-run-ediff-merge]\t\tEdiff-merge current buffer with candidate. With two marked buffers, ediff-merge those buffers.
|
\\[helm-buffer-diff-persistent]\t\tToggle Diff-buffer with saved file without leaving Helm.
|
\\[helm-buffer-revert-persistent]\t\tRevert buffer without leaving Helm.
|
\\[helm-buffer-save-persistent]\t\tSave buffer without leaving Helm.
|
\\[helm-buffer-run-kill-buffers]\t\tDelete marked buffers and leave Helm.
|
\\[helm-buffer-run-kill-persistent]\t\tDelete buffer without leaving Helm.
|
\\[helm-buffer-run-rename-buffer]\t\tRename buffer.
|
\\[helm-toggle-all-marks]\t\tToggle all marks.
|
\\[helm-mark-all]\t\tMark all.
|
\\[helm-toggle-buffers-details]\t\tToggle details.
|
\\[helm-buffers-toggle-show-hidden-buffers]\t\tShow hidden buffers.
|
\\[helm-buffers-mark-similar-buffers]\t\tMark all buffers of the same type (color) as current buffer.")
|
|
;;; Find files help (`helm-find-files')
|
;;
|
;;
|
(defvar helm-ff-help-message
|
"* Helm Find Files
|
|
** Tips
|
|
*** Navigation summary
|
|
For a better experience you can enable auto completion by setting
|
`helm-ff-auto-update-initial-value' to non-nil in your init file. It is not
|
enabled by default to not confuse new users.
|
|
**** Use `\\<helm-find-files-map>\\[helm-execute-persistent-action]' (persistent action) on a directory to go down one level
|
|
On a symlinked directory a prefix argument expands to its true name.
|
|
**** Use `\\<helm-find-files-map>\\[helm-find-files-up-one-level]' on a directory to go up one level
|
|
**** Use `\\<helm-find-files-map>\\[helm-find-files-down-last-level]' to walk back the resulting tree of all the `\\<helm-map>\\[helm-execute-persistent-action]' you did
|
|
The tree is reinitialized each time you browse a new tree with
|
`\\<helm-map>\\[helm-execute-persistent-action]' or by entering some pattern in the prompt.
|
|
**** `RET' behavior
|
|
It behaves differently depending on `helm-selection' (current candidate in helm-buffer):
|
|
- candidate basename is \".\" => Open it in dired.
|
- candidate is a directory => Expand it.
|
- candidate is a file => Open it.
|
|
If you have marked candidates and you press RET on a directory,
|
helm will navigate to this directory, if you want to exit with
|
RET with default action with these marked candidates, press RET
|
on a second time while you are on the root of this directory
|
e.g. \"/home/you/dir/.\" or press RET on any file which is not a
|
directory. You can also exit with default action at any moment
|
with `f1'.
|
|
Note that when copying, renaming, etc. from `helm-find-files' the
|
destination file is selected with `helm-read-file-name'.
|
|
To avoid confusion when using `read-file-name' or `read-directory-name', `RET'
|
follows its standard Emacs behaviour, i.e. it exits the minibuffer as soon as
|
you press `RET'. If you want the same behavior as in `helm-find-files', bind
|
`helm-ff-RET' to the `helm-read-file-map':
|
|
(define-key helm-read-file-map (kbd \"RET\") 'helm-ff-RET)
|
|
*** Find file at point
|
|
Helm uses `ffap' partially or completely to find file at point depending on the
|
value of `helm-ff-guess-ffap-filenames': if non-nil, support is complete
|
\(annoying), if nil, support is partial.
|
|
**** Find file at line number
|
|
When text at point is in the form of
|
|
~/elisp/helm/helm.el:1234
|
|
Helm finds this file at the indicated line number, here 1234.
|
|
**** Find URL at point
|
|
When a URL is found at point, Helm expands to that URL only.
|
Pressing `RET' opens that URL using `browse-url-browser-function'.
|
|
**** Find e-mail address at point
|
|
When an e-mail address is found at point, Helm expands to this e-mail address
|
prefixed with \"mailto:\". Pressing `RET' opens a message buffer with that
|
e-mail address.
|
|
*** Quick pattern expansion
|
|
**** Enter `~/' at end of pattern to quickly reach home directory
|
|
**** Enter `/' at end of pattern to quickly reach the file system root
|
|
**** Enter `./' at end of pattern to quickly reach `default-directory'
|
|
\(As per its value at the beginning of the session.)
|
|
If you already are in the `default-directory' this will move the cursor to the top.
|
|
**** Enter `../' at end of pattern will reach upper directory, moving cursor to the top
|
|
This is different from using `\\<helm-find-files-map>\\[helm-find-files-up-one-level]' in that it moves
|
the cursor to the top instead of remaining on the previous subdir name.
|
|
**** Enter `..name/' at end of pattern to start a recursive search
|
|
It searches directories matching \"name\" under the current directory, see the
|
\"Recursive completion on subdirectories\" section below for more details.
|
|
**** Any environment variable (e.g. `$HOME') at end of pattern gets expanded
|
|
**** Any valid filename yanked after pattern gets expanded
|
|
**** Special case: URL at point
|
|
The quick expansions do not take effect after end a URL, you must kill the
|
pattern first (`\\[helm-delete-minibuffer-contents]').
|
|
*** Helm-find-files supports fuzzy matching
|
|
It starts from the third character of the pattern.
|
|
For instance \"fob\" or \"fbr\" will complete \"foobar\" but \"fb\" needs a
|
third character in order to complete it.
|
|
*** Use `\\[universal-argument] \\[helm-execute-persistent-action]' or `\\[helm-follow-action-forward]' to display an image
|
|
*** `\\[helm-execute-persistent-action]' on a filename expands to that filename in the Helm buffer
|
|
Second hit displays the buffer filename.
|
Third hit kills the buffer filename.
|
Note: `\\[universal-argument] \\[helm-execute-persistent-action]' displays the buffer directly.
|
|
*** Browse images directories with `helm-follow-mode' and navigate up/down
|
|
You can also use `helm-follow-action-forward' and `helm-follow-action-backward' with
|
`\\[helm-follow-action-forward]' and `\\[helm-follow-action-backward]' respectively.
|
|
*** Toggle auto-completion with `\\[helm-ff-run-toggle-auto-update]'
|
|
It is useful when trying to create a new file or directory and you don't want
|
Helm to complete what you are writing.
|
|
Note: On a terminal, the default binding `C-<backspace>' may not work.
|
In this case use `C-c <backspace>'.
|
|
*** You can create a new directory and a new file at the same time
|
|
Simply write the path in the prompt and press `RET', e.g.
|
\"~/new/newnew/newnewnew/my_newfile.txt\".
|
|
*** To create a new directory, append a \"/\" to the new name and press `RET'
|
|
*** To create a new file, enter a filename not ending with \"/\"
|
|
Note that when you enter a new name, this one is prefixed with
|
\[?] if you are in a writable directory. If you are in a directory
|
where you have no write permission the new file name is not
|
prefixed and is colored in red. There is not such distinction
|
when using tramp, new filename just appear on top of buffer.
|
|
*** Recursive search from Helm-find-files
|
|
**** You can use Helm-browse-project (see binding below)
|
|
- With no prefix argument:
|
If the current directory is under version control with either git or hg and
|
helm-ls-git and/or helm-ls-hg are installed, it lists all the files under
|
version control. Otherwise it falls back to Helm-find-files. See
|
https://github.com/emacs-helm/helm-ls-git and
|
https://github.com/emacs-helm/helm-ls-hg.
|
|
- With one prefix argument:
|
List all the files under this directory and other subdirectories
|
\(recursion) and this list of files will be cached.
|
|
- With two prefix arguments:
|
Same but the cache is refreshed.
|
|
**** You can start a recursive search with \"locate\" or \"find\"
|
|
See \"Note\" in the [[Recusive completion on subdirectories][section on subdirectories]].
|
|
Using \"locate\", you can enable the local database with a prefix argument. If the
|
local database doesn't already exists, you will be prompted for its creation.
|
If it exists and you want to refresh it, give it two prefix args.
|
|
When using locate the helm-buffer remains empty until you type something.
|
Regardless Helm uses the basename of the pattern entered in the helm-find-files
|
session by default. Hitting `\\[next-history-element]' should just kick in the
|
locate search with this pattern. If you want Helm to automatically do this, add
|
`helm-source-locate' to `helm-sources-using-default-as-input'.
|
|
**** Recursive completion on subdirectories
|
|
Starting from the directory you are currently browsing, it is possible to have
|
completion of all directories underneath. Say you are at \"/home/you/foo/\" and
|
you want to go to \"/home/you/foo/bar/baz/somewhere/else\", simply type
|
\"/home/you/foo/..else\" and hit `\\[helm-execute-persistent-action]' or enter
|
the final \"/\". Helm will then list all possible directories under \"foo\"
|
matching \"else\".
|
|
Entering two spaces before \"else\" instead of two dots also works.
|
|
Note: Completion on subdirectories uses \"locate\" as backend, you can configure
|
the command with `helm-locate-recursive-dirs-command'. Because this completion
|
uses an index, the directory tree displayed may be out-of-date and not reflect
|
the latest change until you update the index (using \"updatedb\" for \"locate\").
|
|
If for some reason you cannot use an index, the \"find\" command from
|
\"findutils\" can be used instead. It will be slower though. You need to pass
|
the basedir as first argument of \"find\" and the subdir as the value for
|
'-(i)regex' or '-(i)name' with the two format specs that are mandatory in
|
`helm-locate-recursive-dirs-command'.
|
|
Examples:
|
- \"find %s -type d -name '*%s*'\"
|
- \"find %s -type d -regex .*%s.*$\"
|
|
*** Insert filename at point or complete filename at point
|
|
On insertion (not on completion, i.e. there is nothing at point):
|
|
- `\\[helm-ff-run-complete-fn-at-point]': insert absolute file name.
|
- `\\[universal-argument] \\[helm-ff-run-complete-fn-at-point]': insert abbreviated file name.
|
- `\\[universal-argument] \\[universal-argument] \\[helm-ff-run-complete-fn-at-point]': insert relative file name.
|
|
On completion:
|
|
- Target starts with \"~/\": insert abbreviate file name.
|
- target starts with \"/\" or \"[a-z]:/\": insert full path.
|
- Otherwise: insert relative file name.
|
|
*** Use the wildcard to select multiple files
|
|
Use of wilcard is supported to run an action over a set of files.
|
|
Example: You can copy all the files with \".el\" extension by using \"*.el\" and
|
then run copy action.
|
|
Similarly, \"**.el\" (note the two stars) will recursively select all \".el\"
|
files under the current directory.
|
|
Note that when recursively copying files, you may have files with same name
|
dispatched across different subdirectories, so when copying them in the same
|
directory they will get overwritten. To avoid this Helm has a special action
|
called \"backup files\" that has the same behavior as the command line \"cp -f
|
--backup=numbered\": it allows you to copy many files with the same name from
|
different subdirectories into one directory. Files with same name are renamed
|
as follows: \"foo.txt.~1~\". Like with the --force option of cp, it is possible
|
to backup files in current directory.
|
|
This command is available only when `dired-async-mode' is active.
|
|
When using an action that involves an external backend (e.g. grep), using \"**\"
|
is not recommended (even thought it works fine) because it will be slower to
|
select all the files. You are better off leaving the backend to do it, it will
|
be faster. However, if you know you have not many files it is reasonable to use
|
this, also using not recursive wilcard (e.g. \"*.el\") is perfectly fine for
|
this.
|
|
The \"**\" feature is active by default in the option `helm-file-globstar'. It
|
is different from the Bash \"shopt globstar\" feature in that to list files with
|
a named extension recursively you would write \"**.el\" whereas in Bash it would
|
be \"**/*.el\". Directory selection with \"**/\" like Bash \"shopt globstar\"
|
option is not supported yet.
|
|
*** Query replace regexp on filenames
|
|
Replace different parts of a file basename with something else.
|
|
When calling this action you will be prompted twice as with
|
`query-replace', first for the matching expression of the text to
|
replace and second for the replacement text. Several facilities,
|
however, are provided to make the two prompts more powerfull.
|
|
**** Syntax of the first prompt
|
|
In addition to simple regexps, these shortcuts are available:
|
|
- Basename without extension => \"%.\"
|
- Only extension => \".%\"
|
- Substring => \"%:<from>:<to>\"
|
- Whole basename => \"%\"
|
|
**** Syntax of the second prompt
|
|
In addition to a simple string to use as replacement, here is what you can use:
|
|
- A placeholder refering to what you have selected in the first prompt: \"\\@\".
|
|
After this placeholder you can use a search-and-replace syntax à-la sed:
|
|
\"\\@/<regexp>/<replacement>/
|
|
You can select a substring from the string represented by the placeholder:
|
|
\"\\@:<from>:<to>\"
|
|
- A special character representing a number which is incremented: \"\\#\".
|
|
- Shortcuts for `upcase', `downcase' and `capitalize'
|
are available as`%u', `%d' and `%c' respectively.
|
|
**** Examples
|
|
***** Recursively rename all files with \".JPG\" extension to \".jpg\"
|
|
Use the `helm-file-globstar' feature described in [[Using wildcard to select multiple files][recursive globbing]]
|
by entering \"**.JPG\" at the end of the Helm-find-files pattern, then hit
|
\\<helm-map>\\[helm-ff-query-replace-on-filenames]: First \"JPG\", then \"jpg\"
|
and hit `RET'.
|
|
Alternatively you can enter \".%\" at the first prompt, then \"jpg\" and hit
|
`RET'. Note that when using this instead of using \"JPG\" at the first prompt,
|
all extensions will be renamed to \"jpg\" even if the extension of one of the
|
files is, say, \"png\". If you want to keep the original extension you can use
|
\"%d\" at the second prompt (downcase).
|
|
***** Batch-rename files from number 001 to 00x
|
|
Use \"\\#\" inside the second prompt.
|
|
Example 1: To rename the files
|
|
foo.jpg
|
bar.jpg
|
baz.jpg
|
|
to
|
|
foo-001.jpg
|
foo-002.jpg
|
foo-003.jpg
|
|
use \"%.\" as matching regexp and \"foo-\\#\" as replacement string.
|
|
Example 2: To rename the files
|
|
foo.jpg
|
bar.jpg
|
baz.jpg
|
|
to
|
|
foo-001.jpg
|
bar-002.jpg
|
baz-003.jpg
|
|
use as matching regexp \"%.\" and as replacement string \"\\@-\\#\".
|
|
***** Replace a substring
|
|
Use \"%:<from>:<to>\".
|
|
Example: To rename files
|
|
foo.jpg
|
bar.jpg
|
baz.jpg
|
|
to
|
|
fOo.jpg
|
bAr.jpg
|
bAz.jpg
|
|
use as matching regexp \"%:1:2\" and as replacement string \"%u\" (upcase).
|
|
Note that you \*cannot* use \"%.\" and \".%\" along with substring replacement.
|
|
***** Modify the string from the placeholder (\\@)
|
|
- By substring, i.e. only using the substring of the placeholder: \"\\@:<from>:<to>\".
|
The length of placeholder is used for <to> when unspecified.
|
|
Example 1: \"\\@:0:2\" replaces from the beginning to the second char of the placeholder.
|
|
Example 2: \\@:2: replaces from the second char of the placeholder to the end.
|
|
- By search-and-replace: \"\\@/<regexp>/<replacement>/\".
|
|
Incremental replacement is also handled in <replacement>.
|
|
Example 3: \"\\@/foo/bar/\" replaces \"foo\" by \"bar\" in the placeholder.
|
|
Example 4: \"\\@/foo/-\\#/\" replaces \"foo\" in the placeholder by 001, 002, etc.
|
|
***** Clash in replacements (avoid overwriting files)
|
|
When performing any of these replacement operations you may end up with same
|
names as replacement. In such cases Helm numbers the file that would otherwise
|
overwritten. For instance, should you remove the \"-m<n>\" part from the files
|
\"emacs-m1.txt\", \"emacs-m2.txt\" and \"emacs-m3.txt\" you would end up with
|
three files named \"emacs.txt\", the second renaming overwriting first file, and
|
the third renaming overwriting second file and so on. Instead Helm will
|
automatically rename the second and third files as \"emacs(1).txt\" and
|
\"emacs(2).txt\" respectively.
|
|
***** Query-replace on filenames vs. serial-rename action
|
|
Unlike the [[Serial renaming][serial rename]] actions, the files renamed with
|
the query-replace action stay in their initial directory and are not moved to
|
the current directory. As such, using \"\\#\" to serial-rename files only makes
|
sense for files inside the same directory. It even keeps renaming files
|
with an incremental number in the next directories.
|
|
*** Serial-rename
|
|
You can use the serial-rename actions to rename, copy or symlink marked files to
|
a specific directory or in the current directory with all the files numbered
|
incrementally.
|
|
- Serial-rename by renaming:
|
Rename all marked files with incremental numbering to a specific directory.
|
|
- Serial-rename by copying:
|
Copy all marked files with incremental numbering to a specific directory.
|
|
- Serial-rename by symlinking:
|
Symlink all marked files with incremental numbering to a specific directory.
|
|
*** Edit marked files in a dired buffer
|
|
You can open a dired buffer containing only marked files with `\\<helm-find-files-map>\\[helm-ff-run-marked-files-in-dired]'.
|
With a prefix argument you can open this same dired buffer in wdired mode for
|
editing. Note that wildcards are supported as well, so you can use e.g.
|
\"*.txt\" to select all \".txt\" files in the current directory or \"**.txt\" to
|
select all files recursively from the current directory.
|
See [[Use the wildcard to select multiple files]] section above.
|
|
*** Defining default target directory for copying, renaming, etc
|
|
You can customize `helm-dwim-target' to behave differently depending on the
|
windows open in the current frame. Default is to provide completion on all
|
directories associated to each window.
|
|
*** Copying and renaming asynchronously
|
|
If you have the async library installed (if you got Helm from MELPA you do), you
|
can use it for copying/renaming files by enabling `dired-async-mode'.
|
|
Note that even when async is enabled, running a copy/rename action with a prefix
|
argument will execute action synchronously. Moreover it will follow the first
|
file of the marked files in its destination directory.
|
|
When `dired-async-mode' is enabled, an additional action named \"Backup files\"
|
will be available. (Such command is not natively available in Emacs).
|
See [[Use the wildcard to select multiple files]] for details.
|
|
*** Bookmark the `helm-find-files' session
|
|
You can bookmark the `helm-find-files' session with `\\[helm-ff-bookmark-set]'.
|
You can later retrieve these bookmarks by calling `helm-filtered-bookmarks'
|
or, from the current `helm-find-files' session, by hitting `\\[helm-find-files-toggle-to-bookmark]'.
|
|
*** Grep files from `helm-find-files'
|
|
You can grep individual files from `helm-find-files' by using
|
\`\\<helm-find-files-map>\\[helm-ff-run-grep]'. This same command can also
|
recursively grep files from the current directory when called with a prefix
|
argument. In this case you will be prompted for the file extensions to use
|
\(grep backend) or the types of files to use (ack-grep backend). See the
|
`helm-grep-default-command' documentation to set this up. For compressed files
|
or archives, use zgrep with \`\\<helm-find-files-map>\\[helm-ff-run-zgrep]'.
|
|
Otherwise you can use recursive commands like \`\\<helm-find-files-map>\\[helm-ff-run-grep-ag]' or `\\<helm-find-files-map>\\[helm-ff-run-git-grep]'
|
that are much faster than using `\\<helm-find-files-map>\\[helm-ff-run-grep]' with a prefix argument.
|
See `helm-grep-ag-command' and `helm-grep-git-grep-command' to set this up.
|
|
You can also use \"id-utils\"' GID with \`\\<helm-find-files-map>\\[helm-ff-run-gid]'
|
by creating an ID index file with the \"mkid\" shell command.
|
|
All those grep commands use the symbol at point as the default pattern.
|
Note that default is different from input (nothing is added to the prompt until
|
you hit `\\[next-history-element]').
|
|
**** Grepping on remote files
|
|
On remote files grep is not well supported by TRAMP unless you suspend updates before
|
entering the pattern and re-enable it once your pattern is ready.
|
To toggle suspend-update, use `\\<helm-map>\\[helm-toggle-suspend-update]'.
|
|
*** Setting up aliases in Eshell allows you to set up powerful customized commands
|
|
Adding Eshell aliases to your `eshell-aliases-file' or using the
|
`alias' command from Eshell allows you to create personalized
|
commands not available in `helm-find-files' actions and use them
|
from `\\<helm-find-files-map>\\[helm-ff-run-eshell-command-on-file]'.
|
|
Example: You want a command to uncompress some \"*.tar.gz\" files from `helm-find-files':
|
|
1) Create an Eshell alias named, say, \"untargz\" with the command
|
\"alias untargz tar zxvf $*\".
|
|
2) Now from `helm-find-files' select the \"*.tar.gz\" file (you can also
|
mark files if needed) and hit `\\<helm-find-files-map>\\[helm-ff-run-eshell-command-on-file]'.
|
|
Note: When using marked files with this, the meaning of the prefix argument is
|
quite subtle. Say you have \"foo\", \"bar\" and \"baz\" marked; when you run
|
the alias command `example' on these files with no prefix argument it will run
|
`example' sequentially on each file:
|
|
$ example foo
|
$ example bar
|
$ example baz
|
|
With a prefix argument however it will apply `example' on all files at once:
|
|
$ example foo bar baz
|
|
Of course the alias command should support this.
|
|
*** Using TRAMP with `helm-find-files' to read remote directories
|
|
`helm-find-files' works fine with TRAMP despite some limitations.
|
|
- Grepping files is not very well supported when used incrementally.
|
See [[Grepping on remote files]].
|
|
- Locate does not work on remote directories.
|
|
**** A TRAMP syntax crash course
|
|
Please refer to TRAMP's documentation for more details.
|
|
- Connect to host 192.168.0.4 as user \"foo\":
|
|
/scp:192.168.0.4@foo:
|
|
- Connect to host 192.168.0.4 as user \"foo\" on port 2222:
|
|
/scp:192.168.0.4@foo#2222:
|
|
- Connect to host 192.168.0.4 as root using multihops syntax:
|
|
/ssh:192.168.0.4@foo|sudo:192.168.0.4:
|
|
Note: You can also use `tramp-default-proxies-alist' when connecting often to
|
the same hosts.
|
|
As a rule of thumb, prefer the scp method unless using multihops (which only
|
works with the ssh method), especially when copying large files.
|
|
You need to hit `C-j' once on top of a directory on the first connection
|
to complete the pattern in the minibuffer.
|
|
**** Display color for directories, symlinks etc... with tramp
|
|
Starting at helm version 2.9.7 it is somewhat possible to
|
colorize fnames by listing files without loosing performances with
|
external commands (ls and awk) if your system is compatible.
|
For this you can use `helm-list-dir-external' as value
|
for `helm-list-directory-function'.
|
|
See `helm-list-directory-function' documentation for more infos.
|
|
**** Completing host
|
|
As soon as you enter the first \":\" after method e.g =/scp:= you will
|
have some completion about previously used hosts or from your =~/.ssh/config=
|
file, hitting `\\[helm-execute-persistent-action]' or `right' on a candidate will insert this host in minibuffer
|
without addind the ending \":\", second hit insert the last \":\".
|
As soon the last \":\" is entered TRAMP will kick in and you should see the list
|
of candidates soon after.
|
|
When connection fails, be sure to delete your TRAMP connection with M-x
|
`helm-delete-tramp-connection' before retrying.
|
|
**** Editing local files as root
|
|
Use the sudo method:
|
|
\"/sudo:host:\" or simply \"/sudo::\".
|
|
*** Attach files to a mail buffer (message-mode)
|
|
If you are in a `message-mode' or `mail-mode' buffer, that action will appear
|
in action menu, otherwise it is available at any time with \\<helm-find-files-map>\\[helm-ff-run-mail-attach-files].
|
It behaves as follows:
|
|
- If you are in a (mail or message) buffer, files are attached there.
|
|
- If you are not in a mail buffer but one or more mail buffers exist, you are
|
prompted to attach files to one of these mail buffers.
|
|
- If you are not in a mail buffer and no mail buffer exists,
|
a new mail buffer is created with the attached files in it.
|
|
*** Open files in separate windows
|
|
When [[Marked candidates][marking]] multiple files or using [[Use the wildcard to select multiple files][wildcard]], helm allow opening all
|
this files in separate windows using an horizontal layout or a
|
vertical layout if you used a prefix arg, when no more windows can be
|
displayed in frame, next files are opened in background without being
|
displayed. When using \\<helm-find-files-map>\\[helm-ff-run-switch-other-window] the current
|
buffer is kept and files are displayed next to it with same behavior as above.
|
When using two prefix args, files are opened in background without beeing displayed.
|
|
*** Expand archives as directories in a avfs directory
|
|
If you have mounted your filesystem with mountavfs,
|
you can expand archives in the \"~/.avfs\" directory with \\<helm-map>\\[helm-execute-persistent-action].
|
|
*** Tramp archive support (emacs-27+ only)
|
|
If your emacs have library tramp-archive.el, you can browse the
|
content of archives with emacs and BTW helm-find-files. However this beeing
|
experimental and not very fast, helm doesn't provide an automatic
|
expansion and detection of archives, you will have to add the final /
|
manually and may have to force update (\\<helm-map>\\[helm-refresh])
|
or remove and add again the final / until tramp finish decompressing archive.
|
|
*** Touch files
|
|
In the completion buffer, you can choose the default which is the current-time, it is
|
the first candidate or the timestamp of one of the selected files.
|
If you need to use something else, use \\<helm-map>\\[next-history-element] and edit
|
the date in minibuffer.
|
It is also a way to quickly create a new file without opening a buffer, saving it
|
and killing it.
|
To touch more than one new file, separate you filenames with a comma (\",\").
|
If one wants to create (touch) a new file with comma inside the name use a prefix arg,
|
this will prevent splitting the name and create multiple files.
|
|
*** Delete files
|
|
You can delete files without quitting helm with
|
`\\<helm-find-files-map>\\[helm-ff-persistent-delete]' or delete files and quit helm with `\\[helm-ff-run-delete-file]'.
|
|
In the second method you can choose to
|
make this command asynchronous by customizing
|
\`helm-ff-delete-files-function'.
|
|
_WARNING_: When deleting files asynchronously you will NOT be
|
WARNED if directories are not empty, that's mean non empty directories will
|
be deleted in background without asking.
|
|
A good compromise is to trash your files
|
when using asynchronous method (see [[Trashing files][Trashing files]]).
|
|
When choosing synchronous delete, you can allow recursive
|
deletion of directories with `helm-ff-allow-recursive-deletes'.
|
Note that when trashing (synchronous) you are not asked for recursive deletion.
|
|
Note that `helm-ff-allow-recursive-deletes' have no effect when
|
deleting asynchronously.
|
|
First method (persistent delete) is always synchronous.
|
|
Note that when a prefix arg is given, trashing behavior is inversed.
|
See [[Trashing files][Trashing files]].
|
|
**** Trashing files
|
|
If you want to trash your files instead of deleting them you can
|
set `delete-by-moving-to-trash' to non nil, like this your files
|
will be moved to trash instead of beeing deleted.
|
|
You can reverse at any time the behavior of `delete-by-moving-to-trash' by using
|
a prefix arg with any of the delete files command.
|
|
On GNULinux distribution, when navigating to a Trash directory you
|
can restore any file in ..Trash/files directory with the 'Restore
|
from trash' action you will find in action menu (needs the
|
trash-cli package installed).
|
You can as well delete files from Trash directories with the 'delete files from trash'
|
action.
|
|
Tip: Navigate to your Trash/files directories with `helm-find-files' and set a bookmark
|
there with \\<helm-find-files-map>\\[helm-ff-bookmark-set] for fast access to Trash.
|
|
_WARNING:_
|
|
If you have an ENV var XDG_DATA_HOME in your .profile or .bash_profile
|
and this var is set to something like $HOME/.local/share (like preconized)
|
`move-file-to-trash' may try to create $HOME/.local/share/Trash (literally)
|
and its subdirs in the directory where you are actually trying to trash files.
|
because `move-file-to-trash' is interpreting XDG_DATA_HOME literally instead
|
of evaling its value (with `substitute-in-file-name').
|
|
***** Trashing remote files with tramp
|
|
Trashing remote files (or local files with sudo method) is disabled by default
|
because tramp is requiring the 'trash' command to be installed, if you want to
|
trash your remote files, customize `helm-trash-remote-files'.
|
The package on most GNU/Linux based distributions is trash-cli, it is available [[https://github.com/andreafrancia/trash-cli][here]].
|
|
NOTE:
|
When deleting your files with sudo method, your trashed files will not be listed
|
with trash-list until you log in as root.
|
|
** Commands
|
\\<helm-find-files-map>
|
\\[helm-ff-run-locate]\t\tRun `locate' (`\\[universal-argument]' to specify locate database, `M-n' to insert basename of candidate).
|
\\[helm-ff-run-browse-project]\t\tBrowse project (`\\[universal-argument]' to recurse, `\\[universal-argument] \\[universal-argument]' to recurse and refresh database).
|
\\[helm-ff-run-find-sh-command]\t\tRun `find' shell command from this directory.
|
\\[helm-ff-run-grep]\t\tRun Grep (`\\[universal-argument]' to recurse).
|
\\[helm-ff-run-pdfgrep]\t\tRun Pdfgrep on marked files.
|
\\[helm-ff-run-zgrep]\t\tRun zgrep (`\\[universal-argument]' to recurse).
|
\\[helm-ff-run-grep-ag]\t\tRun AG grep on current directory.
|
\\[helm-ff-run-git-grep]\t\tRun git-grep on current directory.
|
\\[helm-ff-run-gid]\t\tRun gid (id-utils).
|
\\[helm-ff-run-etags]\t\tRun Etags (`\\[universal-argument]' to use thing-at-point, `\\[universal-argument] \\[universal-argument]' to reload cache).
|
\\[helm-ff-run-rename-file]\t\tRename Files (`\\[universal-argument]' to follow).
|
\\[helm-ff-run-query-replace-fnames-on-marked]\t\tQuery replace on marked files.
|
\\[helm-ff-run-copy-file]\t\tCopy Files (`\\[universal-argument]' to follow).
|
\\[helm-ff-run-byte-compile-file]\t\tByte Compile Files (`\\[universal-argument]' to load).
|
\\[helm-ff-run-load-file]\t\tLoad Files.
|
\\[helm-ff-run-symlink-file]\t\tSymlink Files.
|
\\[helm-ff-run-hardlink-file]\t\tHardlink files.
|
\\[helm-ff-run-relsymlink-file]\t\tRelative symlink Files.
|
\\[helm-ff-run-delete-file]\t\tDelete Files.
|
\\[helm-ff-run-touch-files]\t\tTouch files.
|
\\[helm-ff-run-kill-buffer-persistent]\t\tKill buffer candidate without leaving Helm.
|
\\[helm-ff-persistent-delete]\t\tDelete file without leaving Helm.
|
\\[helm-ff-run-switch-to-eshell]\t\tSwitch to Eshell.
|
\\[helm-ff-run-eshell-command-on-file]\t\tEshell command on file (`\\[universal-argument]' to apply on marked files, otherwise treat them sequentially).
|
\\[helm-ff-run-ediff-file]\t\tEdiff file.
|
\\[helm-ff-run-ediff-merge-file]\t\tEdiff merge file.
|
\\[helm-ff-run-complete-fn-at-point]\t\tComplete file name at point.
|
\\[helm-ff-run-switch-other-window]\t\tSwitch to other window.
|
\\[helm-ff-run-switch-other-frame]\t\tSwitch to other frame.
|
\\[helm-ff-run-open-file-externally]\t\tOpen file with external program (`\\[universal-argument]' to choose).
|
\\[helm-ff-run-preview-file-externally]\t\tPreview file with external program.
|
\\[helm-ff-run-open-file-with-default-tool]\t\tOpen file externally with default tool.
|
\\[helm-ff-rotate-left-persistent]\t\tRotate image left.
|
\\[helm-ff-rotate-right-persistent]\t\tRotate image right.
|
\\[helm-find-files-up-one-level]\t\tGo to parent directory.
|
\\[helm-find-files-history]\t\tSwitch to the visited-directory history.
|
\\[helm-ff-file-name-history]\t\tSwitch to file name history.
|
\\[helm-ff-properties-persistent]\t\tShow file properties in a tooltip.
|
\\[helm-mark-all]\t\tMark all visible candidates.
|
\\[helm-ff-run-toggle-auto-update]\t\tToggle auto-expansion of directories.
|
\\[helm-unmark-all]\t\tUnmark all candidates, visible and invisible ones.
|
\\[helm-ff-run-gnus-attach-files]\t\tGnus' attach files to message buffer.
|
\\[helm-ff-run-print-file]\t\tPrint file, (`\\[universal-argument]' to refresh printer list).
|
\\[helm-enlarge-window]\t\tEnlarge Helm window.
|
\\[helm-narrow-window]\t\tNarrow Helm window.
|
\\[helm-ff-run-toggle-basename]\t\tToggle basename/fullpath.
|
\\[helm-ff-run-find-file-as-root]\t\tFind file as root.
|
\\[helm-ff-run-find-alternate-file]\t\tFind alternate file.
|
\\[helm-ff-run-insert-org-link]\t\tInsert org link.
|
\\[helm-ff-bookmark-set]\t\tSet bookmark to current directory.
|
\\[helm-find-files-toggle-to-bookmark]\t\tJump to bookmark list.")
|
|
;;; Help for `helm-read-file-name'
|
;;
|
;;
|
(defun helm-read-file-name-help-message ()
|
(let ((name (if helm-alive-p
|
(assoc-default 'name (helm-get-current-source))
|
"generic")))
|
(format
|
"* Helm `%s' read file name completion
|
|
This is `%s' read file name completion that have been \"helmized\"
|
because you have enabled [[Helm mode][helm-mode]]'.
|
Don't confuse this with `helm-find-files' which is a native helm command,
|
see [[Helm functions vs helmized emacs functions]].
|
|
** Tips
|
|
*** Navigation
|
|
**** Enter `~/' at end of pattern to quickly reach home directory
|
|
**** Enter `/' at end of pattern to quickly reach the file system root
|
|
**** Enter `./' at end of pattern to quickly reach `default-directory'
|
|
\(As per its value at the beginning of the session.)
|
|
If you already are in the `default-directory' this will move the cursor to the top.
|
|
**** Enter `../' at end of pattern will reach upper directory, moving cursor on top
|
|
This is different from using `\\[helm-find-files-up-one-level]' in that it moves
|
the cursor to the top instead of remaining on the previous subdir name.
|
|
**** You can complete with partial basename
|
|
It starts from the third character of the pattern.
|
|
For instance \"fob\" or \"fbr\" will complete \"foobar\" but \"fb\" needs a
|
third character in order to complete it.
|
|
*** Persistent actions
|
|
By default `helm-read-file-name' uses the persistent actions of `helm-find-files'.
|
|
**** Use `\\[universal-argument] \\<helm-map>\\[helm-execute-persistent-action]' to display an image
|
|
**** `\\<helm-map>\\[helm-execute-persistent-action]' on a filename will expand to this filename in Helm-buffer
|
|
Second hit displays the buffer filename.
|
Third hit kills the buffer filename.
|
Note: `\\[universal-argument] \\<helm-map>\\[helm-execute-persistent-action]' displays the buffer directly.
|
|
**** Browse images directories with `helm-follow-mode' and navigate up/down
|
|
*** Delete characters backward
|
|
When you want to delete characters backward, e.g. to create a new file or directory,
|
auto-update may come in the way when it keeps updating to an existent directory.
|
In that case, type `C-<backspace>' and then `<backspace>'.
|
This should not be needed when copying/renaming files because autoupdate is disabled
|
by default in that case.
|
|
Note: On a terminal, the default binding `C-<backspace>' may not work.
|
In this case use `C-c <backspace>'.
|
|
*** Create new directories and files
|
|
**** You can create a new directory and a new file at the same time
|
|
Simply write the path in prompt and press `RET', e.g.
|
\"~/new/newnew/newnewnew/my_newfile.txt\".
|
|
**** To create a new directory, append a \"/\" at to the new name and press `RET'
|
|
**** To create a new file, enter a filename not ending with \"/\"
|
|
File and directory creation works only with some commands (e.g. `find-file')
|
and it will not work with others where it is not intended to return a file or
|
a directory \(e.g `list-directory').
|
|
*** Exiting minibuffer with empty string
|
|
You can exit minibuffer with empty string with \\<helm-read-file--map>\\[helm-cr-empty-string].
|
It is useful when some commands are prompting continuously until you enter an empty prompt.
|
|
** Commands
|
\\<helm-read-file-map>
|
\\[helm-find-files-up-one-level]\t\tGo to parent directory.
|
\\[helm-ff-run-toggle-auto-update]\t\tToggle auto-expansion of directories.
|
\\[helm-ff-run-toggle-basename]\t\tToggle basename.
|
\\[helm-ff-file-name-history]\t\tFile name history.
|
C/\\[helm-cr-empty-string]\t\tReturn empty string unless `must-match' is non-nil.
|
\\[helm-next-source]\t\tGo to next source.
|
\\[helm-previous-source]\t\tGo to previous source."
|
name name)))
|
|
;;; Generic file help - Used by locate.
|
;;
|
;;
|
(defvar helm-generic-file-help-message
|
"* Helm Generic files
|
|
** Tips
|
|
*** Locate
|
|
You can append to the search pattern any of the locate command line options,
|
e.g. -b, -e, -n <number>, etc. See the locate(1) man page for more details.
|
|
Some other sources (at the moment \"recentf\" and \"file in current directory\")
|
support the -b flag for compatibility with locate when they are used with it.
|
|
When you enable fuzzy matching on locate with `helm-locate-fuzzy-match', the
|
search will be performed on basename only for efficiency (so don't add \"-b\" at
|
prompt). As soon as you separate the patterns with spaces, fuzzy matching will
|
be disabled and search will be done on the full filename. Note that in
|
multi-match, fuzzy is completely disabled, which means that each pattern is a
|
match regexp (i.e. \"helm\" will match \"helm\" but \"hlm\" will \*not* match
|
\"helm\").
|
|
*** Browse project
|
|
When the current directory is not under version control, don't forget to refresh
|
the cache when files have been added/removed in the directory.
|
|
*** Find command
|
|
Recursively search files using the \"find\" shell command.
|
|
Candidates are all filenames that match all given globbing patterns. This
|
respects the options `helm-case-fold-search' and
|
`helm-findutils-search-full-path'.
|
|
You can pass arbitrary \"find\" options directly after a \"*\" separator.
|
For example, this would find all files matching \"book\" that are larger
|
than 1 megabyte:
|
|
book * -size +1M
|
|
** Commands
|
\\<helm-generic-files-map>
|
\\[helm-ff-run-toggle-basename]\t\tToggle basename.
|
\\[helm-ff-run-grep]\t\tRun grep (`\\[universal-argument]' to recurse).
|
\\[helm-ff-run-zgrep]\t\tRun zgrep.
|
\\[helm-ff-run-gid]\t\tRun GID (id-utils).
|
\\[helm-ff-run-pdfgrep]\t\tRun PDFgrep on marked files.
|
\\[helm-ff-run-copy-file]\t\tCopy file(s)
|
\\[helm-ff-run-rename-file]\t\tRename file(s).
|
\\[helm-ff-run-symlink-file]\t\tSymlink file(s).
|
\\[helm-ff-run-hardlink-file]\t\tHardlink file(s).
|
\\[helm-ff-run-delete-file]\t\tDelete file(s).
|
\\[helm-ff-run-byte-compile-file]\t\tByte compile Elisp file(s) (`\\[universal-argument]' to load).
|
\\[helm-ff-run-load-file]\t\tLoad Elisp file(s).
|
\\[helm-ff-run-ediff-file]\t\tEdiff file.
|
\\[helm-ff-run-ediff-merge-file]\t\tEdiff-merge file.
|
\\[helm-ff-run-switch-other-window]\t\tSwitch to other window.
|
\\[helm-ff-properties-persistent]\t\tShow file properties.
|
\\[helm-ff-run-etags]\t\tRun etags (`\\[universal-argument]' to use tap, `\\[universal-argument] \\[universal-argument]' to reload the database).
|
\\[helm-yank-text-at-point]\t\tYank text at point.
|
\\[helm-ff-run-open-file-externally]\t\tOpen file with external program (`\\[universal-argument]' to choose).
|
\\[helm-ff-run-open-file-with-default-tool]\t\tOpen file externally with default tool.
|
\\[helm-ff-run-insert-org-link]\t\tInsert org link.")
|
|
;;; Grep help
|
;;
|
;;
|
(defvar helm-grep-help-message
|
"* Helm Grep
|
|
** Tips
|
|
*** Use a prefix argument to grep recursively
|
|
With Helm supporting git-grep and AG however, you are better off using one of
|
them for recursive searches.
|
|
*** You can use wild cards when selecting files (e.g. \"*.el\")
|
|
*** You can grep in many different directories by marking files or using wild cards
|
|
*** You can save the result in a `helm-grep-mode' buffer
|
|
See [[Commands][commands]] below.
|
|
Once in that buffer you can use \"emacs-wgrep\" (external package not bundled with Helm)
|
to edit your changes.
|
|
*** Helm-grep supports multi-matching
|
|
\(Starting from version 1.9.4.)
|
|
Simply add a space between each pattern as for most Helm commands.
|
|
*** See full path of selected candidate
|
|
Add (helm-popup-tip-mode 1) in your init file or enable it interactively with
|
M-x helm-popup-tip-mode.
|
|
*** Open file in other window
|
|
The command \\<helm-grep-map>\\[helm-grep-run-other-window-action] allow you to open file
|
in other window horizontally or vertically if a prefix arg is supplied.
|
|
*** Performance over TRAMP
|
|
Grepping works but it is badly supported as TRAMP doesn't support multiple
|
processes running in a short delay (less than 5s) among other things.
|
|
Helm uses a special hook to suspend the process automatically while you are
|
typing. Even if Helm handles this automatically by delaying each process by 5s,
|
you are adviced to this manually by hitting `\\<helm-map>\\[helm-toggle-suspend-update]' (suspend process) before
|
typing, and hit again `\\<helm-map>\\[helm-toggle-suspend-update]' when the regexp is ready to send to the remote
|
process. For simple regexps, there should be no need for this.
|
|
Another solution is to not use TRAMP at all and mount your remote file system via
|
SSHFS.
|
|
* Helm GID
|
|
** Tips
|
|
Helm-GID reads the database created with the `mkid' command from id-utils.
|
The name of the database file can be customized with `helm-gid-db-file-name', it
|
is usually \"ID\".
|
|
Helm-GID use the symbol at point as default-input. This command is also
|
accessible from `helm-find-files' which allow you to navigate to another
|
directory to consult its database.
|
|
Note: Helm-GID supports multi-matches but only the last pattern entered will be
|
highlighted since there is no ~--color~-like option in GID itself.
|
|
* Helm AG
|
|
** Tips
|
|
Helm-AG is different from grep or ack-grep in that it works on a directory and
|
not on a list of files.
|
|
You can ignore files and directories with a \".agignore\" file, local to a
|
directory or global when placed in the home directory. \(See the AG man page for
|
more details.) That file follows the same syntax as `helm-grep-ignored-files'
|
and `helm-grep-ignored-directories'.
|
|
As always you can access Helm AG from `helm-find-files'.
|
|
Starting with version 0.30, AG accepts one or more TYPE arguments on its command
|
line. Helm provides completion on these TYPE arguments when available with your
|
AG version. Use a prefix argument when starting a Helm-AG session to enable this
|
completion.
|
|
Note: You can mark several types to match in the AG query. The first AG
|
versions providing this feature allowed only one type, so in this case only the
|
last mark will be used.
|
|
* Helm git-grep
|
|
Helm-git-grep searches the current directory, i.e the default directory or the
|
directory in Helm-find-files. If this current directory is a subdirectory of a
|
project and you want to also match parent directories (i.e the whole project),
|
use a prefix argument.
|
|
** Commands
|
\\<helm-grep-map>
|
\\[helm-goto-next-file]\t\tNext File.
|
\\[helm-goto-precedent-file]\t\tPrevious File.
|
\\[helm-yank-text-at-point]\t\tYank text at point in minibuffer.
|
\\[helm-grep-run-other-window-action]\t\tJump to other window.
|
\\[helm-grep-run-other-frame-action]\t\tJump to other frame.
|
\\[helm-grep-run-default-action]\t\tRun default action (same as `RET').
|
\\[helm-grep-run-save-buffer]\t\tSave to a `helm-grep-mode' enabled buffer.")
|
|
;;; PDF grep help
|
;;
|
;;
|
(defvar helm-pdfgrep-help-message
|
"* Helm PDFgrep Map
|
|
** Commands
|
\\<helm-pdfgrep-map>
|
\\[helm-goto-next-file]\t\tNext file.
|
\\[helm-goto-precedent-file]\t\tPrevious file.
|
\\[helm-yank-text-at-point]\t\tYank text at point in minibuffer.")
|
|
;;; Etags help
|
;;
|
;;
|
(defvar helm-etags-help-message
|
"* Helm Etags Map
|
|
** Commands
|
\\<helm-etags-map>
|
\\[helm-goto-next-file]\t\tNext file.
|
\\[helm-goto-precedent-file]\t\tPrevious file.
|
\\[helm-yank-text-at-point]\t\tYank text at point in minibuffer.")
|
|
;;; UCS help
|
;;
|
;;
|
(defvar helm-ucs-help-message
|
"* Helm UCS
|
|
** Tips
|
|
Use commands below to insert unicode characters in current buffer without
|
leaving Helm.
|
|
** Commands
|
\\<helm-ucs-map>
|
\\[helm-ucs-persistent-insert]\t\tInsert character.
|
\\[helm-ucs-persistent-forward]\t\tForward character.
|
\\[helm-ucs-persistent-backward]\t\tBackward character.
|
\\[helm-ucs-persistent-delete]\t\tDelete character backward.
|
\\[helm-ucs-persistent-insert-space]\t\tInsert space.")
|
|
;;; Bookmark help
|
;;
|
;;
|
(defvar helm-bookmark-help-message
|
"* Helm bookmark name
|
|
** Commands
|
\\<helm-bookmark-map>
|
\\[helm-bookmark-run-jump-other-window]\t\tJump other window.
|
\\[helm-bookmark-run-delete]\t\tDelete bookmark.
|
\\[helm-bookmark-run-edit]\t\tEdit bookmark.
|
\\[helm-bookmark-toggle-filename]\t\tToggle bookmark location visibility.")
|
|
;;; Eshell command on file help
|
;;
|
;;
|
(defvar helm-esh-help-message
|
"* Helm Eshell on file
|
|
** Tips
|
|
*** Pass extra arguments after filename
|
|
Normally the command or alias will be called with file as argument. For instance
|
|
<command> candidate_file
|
|
But you can also pass an argument or more after \"candidate_file\" like this:
|
|
<command> %s [extra_args]
|
|
\"candidate_file\" will be added at \"%s\" and the command will look at this:
|
|
<command> candidate_file [extra_args]
|
|
*** Specify marked files as arguments
|
|
Example:
|
|
<command> file1 file2...
|
|
Call `helm-find-files-eshell-command-on-file' with one prefix argument. Otherwise
|
you can pass one prefix argument from the command selection buffer.
|
|
Note: This does not work on remote files.
|
|
With two prefix-args the output is printed to the `current-buffer'.
|
|
With no prefix argument or a prefix argument value of '(16) (`\\[universal-argument] \\[universal-argument]')
|
the command is called once for each file like this:
|
|
<command> file1
|
<command> file2
|
...
|
|
** Commands
|
\\<helm-esh-on-file-map>")
|
|
;;; Ido virtual buffer help
|
;;
|
;;
|
(defvar helm-buffers-ido-virtual-help-message
|
"* Helm Ido virtual buffers
|
|
** Commands
|
\\<helm-buffers-ido-virtual-map>
|
\\[helm-ff-run-switch-other-window]\t\tSwitch to other window.
|
\\[helm-ff-run-switch-other-frame]\t\tSwitch to other frame.
|
\\[helm-ff-run-grep]\t\tGrep file.
|
\\[helm-ff-run-zgrep]\t\tZgrep file.
|
\\[helm-ff-run-delete-file]\t\tDelete file.
|
\\[helm-ff-run-open-file-externally]\t\tOpen file externally.")
|
|
;;; Moccur help
|
;;
|
;;
|
(defvar helm-moccur-help-message
|
"* Helm Moccur
|
|
** Tips
|
|
*** Matching
|
|
Multiple regexp matching is allowed, simply enter a space to separate the regexps.
|
|
Matching empty lines is supported with the regexp \"^$\", you then get the
|
results displayed as the buffer-name and the line number only. You can
|
save and edit these results, i.e. add text to the empty line.
|
|
*** Automatically match symbol at point
|
|
Helm can automatically match the symbol at point while keeping the minibuffer
|
empty, ready to be written to. This behaviour is disabled by default. To
|
enable this you need to add `helm-source-occur' and `helm-source-moccur' to
|
`helm-sources-using-default-as-input'.
|
|
*** Jump to the corresponding line in the searched buffer
|
|
You can do this with `\\<helm-map>\\[helm-execute-persistent-action]' (persistent-action), to do it repeatedly
|
you can use `\\<helm-map>\\[helm-follow-action-forward]' and `\\<helm-map>\\[helm-follow-action-backward]' or enable `helm-follow-mode' with `\\<helm-map>\\[helm-follow-mode]'.
|
|
*** Switch to buffer in other window
|
|
The command \\<helm-moccur-map>\\[helm-moccur-run-goto-line-ow] allow you to switch to buffer
|
in other window horizontally or vertically if a prefix arg is supplied.
|
|
*** Save the results
|
|
Similarly to Helm-grep, you can save the results with `\\<helm-map>\\[helm-moccur-run-save-buffer]'.
|
Once in the saved buffer, you can edit it, see [[Edit a saved buffer][below]].
|
|
Of course if you don't save the results, you can resume the Helm session with
|
`helm-resume'.
|
|
*** Refresh the resumed session
|
|
When the buffer(s) where you ran helm-(m)occur get(s) modified, the Helm buffer
|
will flash red as a warning. You can refresh the buffer by running `\\<helm-map>\\[helm-refresh]'.
|
This can be done automatically by customizing `helm-moccur-auto-update-on-resume'.
|
|
*** Refresh a saved buffer
|
|
Type `g' to update the buffer.
|
|
*** Edit a saved buffer
|
|
First, install wgrep (https://github.com/mhayashi1120/Emacs-wgrep) and then:
|
|
1) `C-c C-p' (`wgrep-change-to-wgrep-mode') to edit the buffer(s).
|
2) `C-x C-s' to save your changes.
|
|
Tip: Use the excellent iedit (https://github.com/victorhge/iedit) to modify all
|
occurences at once in the buffer.
|
|
*** Search in region
|
|
When searching in current-buffer with `helm-occur', if a region
|
is found helm will search in this region only. If you marked
|
this region with `mark-defun' the symbol that was at point before
|
marking defun will be used when `helm-source-occur' is member of
|
`helm-sources-using-default-as-input'.
|
|
** Commands
|
\\<helm-moccur-map>
|
\\[helm-goto-next-file]\t\tNext buffer.
|
\\[helm-goto-precedent-file]\t\tPrevious buffer.
|
\\[helm-yank-text-at-point]\t\tYank text at point in minibuffer.
|
\\[helm-moccur-run-goto-line-ow]\t\tGo to line in other window.
|
\\[helm-moccur-run-goto-line-of]\t\tGo to line in new frame.")
|
|
;;; Helm Top
|
;;
|
;;
|
(defvar helm-top-help-message
|
"* Helm Top
|
|
** Commands
|
\\<helm-top-map>
|
\\[helm-top-run-sort-by-com]\t\tSort by commands.
|
\\[helm-top-run-sort-by-cpu]\t\tSort by CPU usage.
|
\\[helm-top-run-sort-by-user]\t\tSort alphabetically by user.
|
\\[helm-top-run-sort-by-mem]\t\tSort by memory.")
|
|
;;; Helm Elisp package
|
;;
|
;;
|
(defvar helm-el-package-help-message
|
"* Helm Elisp package
|
|
** Tips
|
|
*** Compile all your packages asynchronously
|
|
If you use async (if you have installed Helm from MELPA you do), only \"helm\",
|
\"helm-core\", and \"magit\" are compiled asynchronously. If you want all your
|
packages compiled asynchronously, add this to your init file:
|
|
(setq async-bytecomp-allowed-packages '(all))
|
|
*** Upgrade Elisp packages
|
|
On initialization (when Emacs is fetching packages on remote), if Helm finds
|
packages to upgrade, it will start in the upgradable packages view showing the packages
|
available for upgrade.
|
|
On subsequent runs, you will have to refresh the list with `C-c \\[universal-argument]'. If Helm
|
finds upgrades you can switch to upgrade view (see below) to see what packages
|
are available for upgrade or simply hit `C-c U' to upgrade them all.
|
|
To see upgradable packages hit `M-U'.
|
|
Then you can install all upgradable packages with the \"upgrade all\" action
|
\(`C-c \\[universal-argument]'), or upgrade only specific packages by marking them and running the
|
\"upgrade\" action (visible only when there are upgradable packages). Of course
|
you can upgrade a single package by just running the \"upgrade\" action without
|
marking it (`C-c u' or `RET') .
|
|
\*Warning:* You are strongly advised to \*restart* Emacs after \*upgrading* packages.
|
|
*** Meaning of flags prefixing packages
|
|
\(Emacs ≥25)
|
|
- The flag \"S\" that prefixes package names means that the packages belong to `package-selected-packages'.
|
|
- The flag \"U\" that prefix package names mean that this package is no more needed.
|
|
** Commands
|
\\<helm-el-package-map>
|
\\[helm-el-package-show-all]\t\tShow all packages.
|
\\[helm-el-package-show-installed]\t\tShow installed packages only.
|
\\[helm-el-package-show-uninstalled]\t\tShow non-installed packages only.
|
\\[helm-el-package-show-upgrade]\t\tShow upgradable packages only.
|
\\[helm-el-package-show-built-in]\t\tShow built-in packages only.
|
\\[helm-el-run-package-install]\t\tInstall package(s).
|
\\[helm-el-run-package-reinstall]\t\tReinstall package(s).
|
\\[helm-el-run-package-uninstall]\t\tUninstall package(s).
|
\\[helm-el-run-package-upgrade]\t\tUpgrade package(s).
|
\\[helm-el-run-package-upgrade-all]\t\tUpgrade all packages.
|
\\[helm-el-run-visit-homepage]\t\tVisit package homepage.")
|
|
;;; Helm M-x
|
;;
|
;;
|
(defvar helm-M-x-help-message
|
"* Helm M-x
|
|
** Tips
|
|
*** You can get help on any command with persistent action (\\[helm-execute-persistent-action])
|
|
*** Prefix arguments
|
|
You must pass prefix arguments \*after* starting `helm-M-x'. A mode-line
|
counter will display the number of given prefix arguments.
|
|
If you pass prefix arguments before running `helm-M-x', it will be displayed in the prompt.
|
The first `\\[universal-argument]' after `helm-M-x' clears those prefix arguments.")
|
|
;;; Helm imenu
|
;;
|
;;
|
(defvar helm-imenu-help-message
|
"* Helm Imenu
|
|
** Commands
|
\\<helm-imenu-map>
|
\\[helm-imenu-next-section]\t\tGo to next section.
|
\\[helm-imenu-previous-section]\t\tGo to previous section.")
|
|
;;; Helm colors
|
;;
|
;;
|
(defvar helm-colors-help-message
|
"* Helm colors
|
|
** Commands
|
\\<helm-color-map>
|
\\[helm-color-run-insert-name]\t\tInsert the entry name.
|
\\[helm-color-run-kill-name]\t\tKill the entry name.
|
\\[helm-color-run-insert-rgb]\t\tInsert entry in RGB format.
|
\\[helm-color-run-kill-rgb]\t\tKill entry in RGB format.")
|
|
;;; Helm Semantic
|
;;
|
;;
|
(defvar helm-semantic-help-message
|
"* Helm Semantic
|
|
** Commands
|
\\<helm-semantic-map>")
|
|
;;; Helm kmacro
|
;;
|
;;
|
(defvar helm-kmacro-help-message
|
"* Helm kmacro
|
|
** Tips
|
|
- Start recording a kmacro with `f3'.
|
- End the kmacro recording with `f4'.
|
- Run `helm-execute-kmacro' to list all your kmacros.
|
|
Use persistent action to run your kmacro as many time as needed.
|
You can browse the kmacros with `helm-next-line' and `helm-previous-line'.
|
|
Note: You can't record keys running Helm commands except `helm-M-x', under the
|
condition that you don't choose a command using Helm completion.
|
|
** Commands
|
\\<helm-kmacro-map>")
|
|
;;; Kill ring
|
;;
|
;;
|
(defvar helm-kill-ring-help-message
|
"* Helm kill ring
|
|
** Tips
|
|
Every Helm session lets you save a candidate to the kill-ring / clipboard /
|
primary-selection with `\\<helm-map>\\[helm-kill-selection-and-quit]'.
|
|
To save space, Helm-kill-ring truncates the candidates longer than
|
`helm-kill-ring-max-offset'.
|
`\\<helm-kill-ring-map>\\[helm-kill-ring-kill-selection]' then saves the whole
|
text and not the truncated value. The view of truncated candidates can be
|
toggled; see the command list below.
|
|
As opposed to `yank', numeric prefix arguments are ignored with
|
`helm-show-kill-ring': there is no need for them since selection happens within
|
Helm. Moreover Helm has [[Shortcuts for executing Default Action on the nth
|
candidate][Shortcuts for executing Default Action on the nth candidate]].
|
|
It is recommended to globally bind `M-y' to `helm-show-kill-ring'. Once in the
|
Helm-kill-ring session you can navigate to next/previous line with `M-y' and
|
`M-u' for convenience. Of course `\\[helm-next-line]' and `\\[helm-previous-line]' are still available.
|
|
It is possible to delete candidates from the kill ring.
|
|
You can concatenate marked candidates and yank them in the current
|
buffer, thus creating a new entry in the kill ring. Candidates are
|
concatenated with `helm-kill-ring-separator' as default but you can
|
change interactively the separator while yanking by using two prefix
|
args. When you have something else than \"\\n\" as default value for
|
`helm-kill-ring-separator' and you want to use \"\\n\" from prompt, use
|
`C-q C-j' to enter a newline in prompt.
|
|
To not push a new entry in the kill ring, use `\\<helm-map>\\[helm-copy-to-buffer]' instead of RET
|
\(note that you can't change separator with this).
|
|
When inserting candidates with the default action (`RET'), `point' is placed at
|
the end of the candidate and `mark' at the beginning. You can revert this behavior
|
by using a prefix argument, i.e. `C-u RET', like the regular `yank' command does.
|
|
** Commands
|
\\<helm-kill-ring-map>
|
\\[helm-next-line]\t\tNext line.
|
\\[helm-previous-line]\t\tPrevious line.
|
\\[helm-kill-ring-delete]\t\tDelete entry.
|
\\[helm-kill-ring-toggle-truncated]\t\tToggle truncated view of candidate.
|
\\[helm-kill-ring-kill-selection]\t\tKill non-truncated of selection.")
|
|
;;; Org headings
|
;;
|
;;
|
(defvar helm-org-headings-help-message
|
"* Helm Org headings
|
|
** Tips
|
|
*** Refiling
|
|
You can refile one or more headings at a time.
|
|
To refile one heading, move the point to the entry you want to refile and run
|
\\[helm-org-in-buffer-headings]. Then select the heading you want to refile to
|
and press \\<helm-org-headings-map>\\[helm-org-run-refile-heading-to] or select the refile action from the actions menu.
|
|
To refile multiple headings, run \\[helm-org-in-buffer-headings] and mark the
|
headings you want to refile. Then select the heading you want to refile to
|
\(without marking it) and press \\<helm-org-headings-map>\\[helm-org-run-refile-heading-to] or select the refile action from the
|
actions menu.
|
|
*** Tags completion
|
|
Tags completion use `completing-read-multiple', perhaps have a
|
look at its docstring.
|
|
**** Single tag
|
|
From an org heading hit C-c C-c which provide a
|
\"Tags\" prompt, then hit TAB and RET if you want to enter an
|
existing tag or write a new tag in prompt. At this point you end
|
up with an entry in your prompt, if you enter RET, the entry is
|
added as tag in your org header.
|
|
**** Multiple tags
|
|
If you want to add more tag to your org header, add a separator[1] after
|
your tag and write a new tag or hit TAB to find another existing
|
tag, and so on until you have all the tags you want
|
e.g \"foo,bar,baz\" then press RET to finally add the tags to your
|
org header.
|
Note: [1] A separator can be a comma, a colon i.e. [,:] or a space.
|
|
** Commands
|
\\<helm-org-headings-map>
|
\\[helm-org-run-open-heading-in-indirect-buffer]\t\tOpen heading in indirect buffer.
|
\\[helm-org-run-refile-heading-to]\t\tRefile current or marked headings to selection.
|
\\[helm-org-run-insert-link-to-heading-at-marker]\t\tInsert link at point to selection."
|
)
|
|
;;; Completing-read
|
;;
|
(defun helm-comp-read-help-message ()
|
(let ((com (assoc-default 'name (helm-get-current-source))))
|
(format
|
"* Helm completing-read completion for `%s'
|
|
Command `%s' is using a `completing-read' for completion on your input,
|
this completion have been \"helmized\" because you have enabled [[Helm mode][helm-mode]]'.
|
|
** Tips
|
|
*** Disabling or use something else than helm for completion of some commands
|
|
You can disable helm completion or use something else for specific commands of your choice,
|
for this customize variable `helm-completing-read-handlers-alist'.
|
|
*** Exiting minibuffer with empty string
|
|
You can exit minibuffer with empty string with \\<helm-comp-read-map>\\[helm-cr-empty-string].
|
It is useful when some commands are prompting continuously until you enter an empty prompt.
|
|
** Commands
|
\\<helm-comp-read-map>
|
\\[helm-cr-empty-string]\t\tExit minibuffer with empty string."
|
com com)))
|
|
|
;;; Mode line strings
|
;;
|
;;
|
;;;###autoload
|
(defvar helm-comp-read-mode-line "\
|
\\<helm-comp-read-map>\
|
C/\\[helm-cr-empty-string]:Empty \
|
\\<helm-map>\
|
\\[helm-help]:Help \
|
\\[helm-select-action]:Act \
|
\\[helm-maybe-exit-minibuffer]/\
|
f1/f2/f-n:NthAct \
|
\\[helm-toggle-suspend-update]:Tog.suspend")
|
|
;;;###autoload
|
(defvar helm-read-file-name-mode-line-string "\
|
\\<helm-read-file-map>\
|
\\[helm-help]:Help \
|
C/\\[helm-cr-empty-string]:Empty \
|
\\<helm-map>\
|
\\[helm-select-action]:Act \
|
\\[helm-maybe-exit-minibuffer]/\
|
f1/f2/f-n:NthAct \
|
\\[helm-toggle-suspend-update]:Tog.suspend"
|
"String displayed in mode-line in `helm-source-find-files'.")
|
|
;;;###autoload
|
(defvar helm-top-mode-line "\
|
\\<helm-top-map>\
|
\\[helm-help]:Help \
|
\\<helm-map>\
|
\\[helm-select-action]:Act \
|
\\[helm-maybe-exit-minibuffer]/\
|
f1/f2/f-n:NthAct \
|
\\[helm-toggle-suspend-update]:Tog.suspend")
|
|
|
(provide 'helm-help)
|
|
;; Local Variables:
|
;; byte-compile-warnings: (not obsolete)
|
;; coding: utf-8
|
;; indent-tabs-mode: nil
|
;; End:
|
|
;;; helm-help.el ends here
|
