| commit | author | age | ||
| 5cb5f7 | 1 | ;;; helm-help.el --- Help messages for Helm. -*- lexical-binding: t -*- |
| C | 2 | |
| 3 | ;; Copyright (C) 2012 ~ 2018 Thierry Volpiatto <thierry.volpiatto@gmail.com> | |
| 4 | ||
| 5 | ;; This program is free software; you can redistribute it and/or modify | |
| 6 | ;; it under the terms of the GNU General Public License as published by | |
| 7 | ;; the Free Software Foundation, either version 3 of the License, or | |
| 8 | ;; (at your option) any later version. | |
| 9 | ||
| 10 | ;; This program is distributed in the hope that it will be useful, | |
| 11 | ;; but WITHOUT ANY WARRANTY; without even the implied warranty of | |
| 12 | ;; MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the | |
| 13 | ;; GNU General Public License for more details. | |
| 14 | ||
| 15 | ;; You should have received a copy of the GNU General Public License | |
| 16 | ;; along with this program. If not, see <http://www.gnu.org/licenses/>. | |
| 17 | ||
| 18 | ;;; Code: | |
| 19 | (require 'helm) | |
| 20 | ||
| 21 | (defvar helm-org-headings--nofilename) | |
| 22 | (declare-function helm-source-org-headings-for-files "helm-org.el") | |
| 23 | ||
| 24 | ||
| 25 | (defgroup helm-help nil | |
| 26 | "Embedded help for `helm'." | |
| 27 | :group 'helm) | |
| 28 | ||
| 29 | (defface helm-helper | |
| 30 | '((t :inherit helm-header)) | |
| 31 | "Face for Helm help string in minibuffer." | |
| 32 | :group 'helm-help) | |
| 33 | ||
| 34 | (defvar helm-help--string-list '(helm-help-message | |
| 35 | helm-buffer-help-message | |
| 36 | helm-ff-help-message | |
| 37 | helm-read-file-name-help-message | |
| 38 | helm-generic-file-help-message | |
| 39 | helm-grep-help-message | |
| 40 | helm-pdfgrep-help-message | |
| 41 | helm-etags-help-message | |
| 42 | helm-ucs-help-message | |
| 43 | helm-bookmark-help-message | |
| 44 | helm-esh-help-message | |
| 45 | helm-buffers-ido-virtual-help-message | |
| 46 | helm-moccur-help-message | |
| 47 | helm-top-help-message | |
| 48 | helm-el-package-help-message | |
| 49 | helm-M-x-help-message | |
| 50 | helm-imenu-help-message | |
| 51 | helm-colors-help-message | |
| 52 | helm-semantic-help-message | |
| 53 | helm-kmacro-help-message)) | |
| 54 | ||
| 55 | (defvar helm-documentation-buffer-name "*helm documentation*") | |
| 56 | ||
| 57 | ;;;###autoload | |
| 58 | (defun helm-documentation () | |
| 59 | "Preconfigured Helm for Helm documentation. | |
| 60 | With a prefix arg refresh the documentation. | |
| 61 | ||
| 62 | Find here the documentation of all documented sources." | |
| 63 | (interactive) | |
| 64 | (require 'helm-org) | |
| 65 | (with-current-buffer (get-buffer-create helm-documentation-buffer-name) | |
| 66 | (let ((inhibit-read-only t)) | |
| 67 | (erase-buffer) | |
| 68 | (cl-loop for elm in helm-help--string-list | |
| 69 | for str = (helm-interpret-value elm) | |
| 70 | do (insert (substitute-command-keys str) "\n\n")) | |
| 71 | (org-mode)) | |
| 72 | (setq buffer-read-only t) | |
| 73 | (view-mode)) | |
| 74 | (let ((helm-org-headings--nofilename t)) | |
| 75 | (helm :sources (helm-source-org-headings-for-files | |
| 76 | (list (get-buffer helm-documentation-buffer-name))) | |
| 77 | :candidate-number-limit 99999 | |
| 78 | :buffer "*helm doc*"))) | |
| 79 | ||
| 80 | ;;; Local help messages. | |
| 81 | ||
| 82 | ;;; `helm-buffer-list' help | |
| 83 | ;; | |
| 84 | ;; | |
| 85 | (defvar helm-buffer-help-message | |
| 86 | "* Helm Buffer | |
| 87 | ||
| 88 | ** Tips | |
| 89 | ||
| 90 | *** Completion | |
| 91 | ||
| 92 | **** Major-mode | |
| 93 | ||
| 94 | You can enter a partial major-mode name (e.g. lisp, sh) to narrow down buffers. | |
| 95 | To specify the major-mode, prefix it with \"*\" e.g. \"*lisp\". | |
| 96 | ||
| 97 | If you want to match all buffers but the ones with a specific major-mode | |
| 98 | \(negation), prefix the major-mode with \"!\" e.g. \"*!lisp\". | |
| 99 | ||
| 100 | If you want to specify more than one major-mode, separate them with \",\", | |
| 101 | e.g. \"*!lisp,!sh,!fun\" lists all buffers but the ones in lisp-mode, sh-mode | |
| 102 | and fundamental-mode. | |
| 103 | ||
| 104 | Then enter a space followed by a pattern to narrow down to buffers matching this | |
| 105 | pattern. | |
| 106 | ||
| 107 | **** Search inside buffers | |
| 108 | ||
| 109 | If you enter a space and a pattern prefixed by \"@\", Helm searches for text | |
| 110 | matching this pattern \*inside* the buffer (i.e. not in the name of the buffer). | |
| 111 | ||
| 112 | If you enter a pattern prefixed with an escaped \"@\", Helm searches for a | |
| 113 | buffer matching \"@pattern\" but does not search inside. | |
| 114 | ||
| 115 | **** Search by directory name | |
| 116 | ||
| 117 | If you prefix the pattern with \"/\", Helm matches over the directory names | |
| 118 | of the buffers. | |
| 119 | ||
| 120 | This feature can be used to narrow down the search to one directory while | |
| 121 | subsequent strings entered after a space match over the buffer name only. | |
| 122 | ||
| 123 | Note that negation is not supported for matching on buffer filename. | |
| 124 | ||
| 125 | Starting from Helm v1.6.8, you can specify more than one directory. | |
| 126 | ||
| 127 | **** Fuzzy matching | |
| 128 | ||
| 129 | `helm-buffers-fuzzy-matching' turns on fuzzy matching on buffer names, but not | |
| 130 | on directory names or major modes. A pattern starting with \"^\" disables fuzzy | |
| 131 | matching and matches by exact regexp. | |
| 132 | ||
| 133 | **** Examples | |
| 134 | ||
| 135 | With the following pattern | |
| 136 | ||
| 137 | \"*lisp ^helm @moc\" | |
| 138 | ||
| 139 | Helm narrows down the list by selecting only the buffers that are in lisp mode, | |
| 140 | start with \"helm\" and which content matches \"moc\". | |
| 141 | ||
| 142 | Without the \"@\" | |
| 143 | ||
| 144 | \"*lisp ^helm moc\" | |
| 145 | ||
| 146 | Helm looks for lisp mode buffers starting with \"helm\" and containing \"moc\" | |
| 147 | in their name. | |
| 148 | ||
| 149 | With this other pattern | |
| 150 | ||
| 151 | \"*!lisp !helm\" | |
| 152 | ||
| 153 | Helm narrows down to buffers that are not in \"lisp\" mode and that do not match | |
| 154 | \"helm\". | |
| 155 | ||
| 156 | With this last pattern | |
| 157 | ||
| 158 | /helm/ w3 | |
| 159 | ||
| 160 | Helm narrows down to buffers that are in any \"helm\" subdirectory and | |
| 161 | matching \"w3\". | |
| 162 | ||
| 163 | *** Creating buffers | |
| 164 | ||
| 165 | When creating a new buffer, use `\\[universal-argument]' to choose a mode from a | |
| 166 | list. This list is customizable, see `helm-buffers-favorite-modes'. | |
| 167 | ||
| 168 | *** Killing buffers | |
| 169 | ||
| 170 | You can kill buffers either one by one or all the marked buffers at once. | |
| 171 | ||
| 172 | One kill-buffer command leaves Helm while the other is persistent. Run the | |
| 173 | persistent kill-buffer command either with the regular | |
| 174 | `helm-execute-persistent-action' called with a prefix argument (`\\[universal-argument] \\<helm-map>\\[helm-execute-persistent-action]') | |
| 175 | or with its specific command `helm-buffer-run-kill-persistent'. See the | |
| 176 | bindings below. | |
| 177 | ||
| 178 | *** Switching to buffers | |
| 179 | ||
| 180 | To switch to a buffer, press RET, to switch to a buffer in another window, select this buffer | |
| 181 | and press \\<helm-buffer-map>\\[helm-buffer-switch-other-window], when called with a prefix arg | |
| 182 | the buffer will be displayed vertically in other window. | |
| 183 | If you mark more than one buffer, the marked buffers will be displayed in different windows. | |
| 184 | ||
| 185 | *** Meaning of colors and prefixes for buffers | |
| 186 | ||
| 187 | Remote buffers are prefixed with '@'. | |
| 188 | Red => Buffer's file was modified on disk by an external process. | |
| 189 | Indianred2 => Buffer exists but its file has been deleted. | |
| 190 | Orange => Buffer is modified and not saved to disk. | |
| 191 | Italic => A non-file buffer. | |
| 192 | Yellow => Tramp archive buffer. | |
| 193 | ||
| 194 | ** Commands | |
| 195 | \\<helm-buffer-map> | |
| 196 | \\[helm-buffer-run-zgrep]\t\tGrep Buffer(s) works as zgrep too (`\\[universal-argument]' to grep all buffers but non-file buffers). | |
| 197 | \\[helm-buffers-run-multi-occur]\t\tMulti-Occur buffer or marked buffers (`\\[universal-argument]' to toggle force-searching current-buffer). | |
| 198 | \\[helm-buffer-switch-other-window]\t\tSwitch to other window. | |
| 199 | \\[helm-buffer-switch-other-frame]\t\tSwitch to other frame. | |
| 200 | \\[helm-buffers-run-browse-project]\t\tBrowse project from buffer. | |
| 201 | \\[helm-buffer-run-query-replace-regexp]\t\tQuery-replace-regexp in marked buffers. | |
| 202 | \\[helm-buffer-run-query-replace]\t\tQuery-replace in marked buffers. | |
| 203 | \\[helm-buffer-run-ediff]\t\tEdiff current buffer with candidate. With two marked buffers, ediff those buffers. | |
| 204 | \\[helm-buffer-run-ediff-merge]\t\tEdiff-merge current buffer with candidate. With two marked buffers, ediff-merge those buffers. | |
| 205 | \\[helm-buffer-diff-persistent]\t\tToggle Diff-buffer with saved file without leaving Helm. | |
| 206 | \\[helm-buffer-revert-persistent]\t\tRevert buffer without leaving Helm. | |
| 207 | \\[helm-buffer-save-persistent]\t\tSave buffer without leaving Helm. | |
| 208 | \\[helm-buffer-run-kill-buffers]\t\tDelete marked buffers and leave Helm. | |
| 209 | \\[helm-buffer-run-kill-persistent]\t\tDelete buffer without leaving Helm. | |
| 210 | \\[helm-buffer-run-rename-buffer]\t\tRename buffer. | |
| 211 | \\[helm-toggle-all-marks]\t\tToggle all marks. | |
| 212 | \\[helm-mark-all]\t\tMark all. | |
| 213 | \\[helm-toggle-buffers-details]\t\tToggle details. | |
| 214 | \\[helm-buffers-toggle-show-hidden-buffers]\t\tShow hidden buffers. | |
| 215 | \\[helm-buffers-mark-similar-buffers]\t\tMark all buffers of the same type (color) as current buffer.") | |
| 216 | ||
| 217 | ;;; Find files help (`helm-find-files') | |
| 218 | ;; | |
| 219 | ;; | |
| 220 | (defvar helm-ff-help-message | |
| 221 | "* Helm Find Files | |
| 222 | ||
| 223 | ** Tips | |
| 224 | ||
| 225 | *** Navigation summary | |
| 226 | ||
| 227 | For a better experience you can enable auto completion by setting | |
| 228 | `helm-ff-auto-update-initial-value' to non-nil in your init file. It is not | |
| 229 | enabled by default to not confuse new users. | |
| 230 | ||
| 231 | **** Use `\\<helm-find-files-map>\\[helm-execute-persistent-action]' (persistent action) on a directory to go down one level | |
| 232 | ||
| 233 | On a symlinked directory a prefix argument expands to its true name. | |
| 234 | ||
| 235 | **** Use `\\<helm-find-files-map>\\[helm-find-files-up-one-level]' on a directory to go up one level | |
| 236 | ||
| 237 | **** 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 | |
| 238 | ||
| 239 | The tree is reinitialized each time you browse a new tree with | |
| 240 | `\\<helm-map>\\[helm-execute-persistent-action]' or by entering some pattern in the prompt. | |
| 241 | ||
| 242 | **** `RET' behavior | |
| 243 | ||
| 244 | It behaves differently depending on `helm-selection' (current candidate in helm-buffer): | |
| 245 | ||
| 246 | - candidate basename is \".\" => Open it in dired. | |
| 247 | - candidate is a directory => Expand it. | |
| 248 | - candidate is a file => Open it. | |
| 249 | - marked candidates (1+) => Open them with default action. | |
| 250 | ||
| 251 | Note that when copying, renaming, etc. from `helm-find-files' the | |
| 252 | destination file is selected with `helm-read-file-name'. | |
| 253 | ||
| 254 | To avoid confusion when using `read-file-name' or `read-directory-name', `RET' | |
| 255 | follows its standard Emacs behaviour, i.e. it exits the minibuffer as soon as | |
| 256 | you press `RET'. If you want the same behavior as in `helm-find-files', bind | |
| 257 | `helm-ff-RET' to the `helm-read-file-map': | |
| 258 | ||
| 259 | (define-key helm-read-file-map (kbd \"RET\") 'helm-ff-RET) | |
| 260 | ||
| 261 | *** Find file at point | |
| 262 | ||
| 263 | Helm uses `ffap' partially or completely to find file at point depending on the | |
| 264 | value of `helm-ff-guess-ffap-filenames': if non-nil, support is complete | |
| 265 | \(annoying), if nil, support is partial. | |
| 266 | ||
| 267 | **** Find file at line number | |
| 268 | ||
| 269 | When text at point is in the form of | |
| 270 | ||
| 271 | ~/elisp/helm/helm.el:1234 | |
| 272 | ||
| 273 | Helm finds this file at the indicated line number, here 1234. | |
| 274 | ||
| 275 | **** Find URL at point | |
| 276 | ||
| 277 | When a URL is found at point, Helm expands to that URL only. | |
| 278 | Pressing `RET' opens that URL using `browse-url-browser-function'. | |
| 279 | ||
| 280 | **** Find e-mail address at point | |
| 281 | ||
| 282 | When an e-mail address is found at point, Helm expands to this e-mail address | |
| 283 | prefixed with \"mailto:\". Pressing `RET' opens a message buffer with that | |
| 284 | e-mail address. | |
| 285 | ||
| 286 | *** Quick pattern expansion | |
| 287 | ||
| 288 | **** Enter `~/' at end of pattern to quickly reach home directory | |
| 289 | ||
| 290 | **** Enter `/' at end of pattern to quickly reach the file system root | |
| 291 | ||
| 292 | **** Enter `./' at end of pattern to quickly reach `default-directory' | |
| 293 | ||
| 294 | \(As per its value at the beginning of the session.) | |
| 295 | ||
| 296 | If you already are in the `default-directory' this will move the cursor to the top. | |
| 297 | ||
| 298 | **** Enter `../' at end of pattern will reach upper directory, moving cursor to the top | |
| 299 | ||
| 300 | This is different from using `\\<helm-find-files-map>\\[helm-find-files-up-one-level]' in that it moves | |
| 301 | the cursor to the top instead of remaining on the previous subdir name. | |
| 302 | ||
| 303 | **** Enter `..name/' at end of pattern to start a recursive search | |
| 304 | ||
| 305 | It searches directories matching \"name\" under the current directory, see the | |
| 306 | \"Recursive completion on subdirectories\" section below for more details. | |
| 307 | ||
| 308 | **** Any environment variable (e.g. `$HOME') at end of pattern gets expanded | |
| 309 | ||
| 310 | **** Any valid filename yanked after pattern gets expanded | |
| 311 | ||
| 312 | **** Special case: URL at point | |
| 313 | ||
| 314 | The quick expansions do not take effect after end a URL, you must kill the | |
| 315 | pattern first (`\\[helm-delete-minibuffer-contents]'). | |
| 316 | ||
| 317 | *** Helm-find-files supports fuzzy matching | |
| 318 | ||
| 319 | It starts from the third character of the pattern. | |
| 320 | ||
| 321 | For instance \"fob\" or \"fbr\" will complete \"foobar\" but \"fb\" needs a | |
| 322 | third character in order to complete it. | |
| 323 | ||
| 324 | *** Use `\\[universal-argument] \\[helm-execute-persistent-action]' or `\\[helm-follow-action-forward]' to display an image | |
| 325 | ||
| 326 | *** `\\[helm-execute-persistent-action]' on a filename expands to that filename in the Helm buffer | |
| 327 | ||
| 328 | Second hit displays the buffer filename. | |
| 329 | Third hit kills the buffer filename. | |
| 330 | Note: `\\[universal-argument] \\[helm-execute-persistent-action]' displays the buffer directly. | |
| 331 | ||
| 332 | *** Browse images directories with `helm-follow-mode' and navigate up/down | |
| 333 | ||
| 334 | You can also use `helm-follow-action-forward' and `helm-follow-action-backward' with | |
| 335 | `\\[helm-follow-action-forward]' and `\\[helm-follow-action-backward]' respectively. | |
| 336 | ||
| 337 | *** Toggle auto-completion with `\\[helm-ff-run-toggle-auto-update]' | |
| 338 | ||
| 339 | It is useful when trying to create a new file or directory and you don't want | |
| 340 | Helm to complete what you are writing. | |
| 341 | ||
| 342 | Note: On a terminal, the default binding `C-<backspace>' may not work. | |
| 343 | In this case use `C-c <backspace>'. | |
| 344 | ||
| 345 | *** You can create a new directory and a new file at the same time | |
| 346 | ||
| 347 | Simply write the path in the prompt and press `RET', e.g. | |
| 348 | \"~/new/newnew/newnewnew/my_newfile.txt\". | |
| 349 | ||
| 350 | *** To create a new directory, append a \"/\" to the new name and press `RET' | |
| 351 | ||
| 352 | *** To create a new file, enter a filename not ending with \"/\" | |
| 353 | ||
| 354 | Note that when you enter a new name, this one is prefixed with | |
| 355 | \[?] if you are in a writable directory. If you are in a directory | |
| 356 | where you have no write permission the new file name is not | |
| 357 | prefixed and is colored in red. There is not such distinction | |
| 358 | when using tramp, new filename just appear on top of buffer. | |
| 359 | ||
| 360 | *** Recursive search from Helm-find-files | |
| 361 | ||
| 362 | **** You can use Helm-browse-project (see binding below) | |
| 363 | ||
| 364 | - With no prefix argument: | |
| 365 | If the current directory is under version control with either git or hg and | |
| 366 | helm-ls-git and/or helm-ls-hg are installed, it lists all the files under | |
| 367 | version control. Otherwise it falls back to Helm-find-files. See | |
| 368 | https://github.com/emacs-helm/helm-ls-git and | |
| 369 | https://github.com/emacs-helm/helm-ls-hg. | |
| 370 | ||
| 371 | - With one prefix argument: | |
| 372 | List all the files under this directory and other subdirectories | |
| 373 | \(recursion) and this list of files will be cached. | |
| 374 | ||
| 375 | - With two prefix arguments: | |
| 376 | Same but the cache is refreshed. | |
| 377 | ||
| 378 | **** You can start a recursive search with \"locate\" or \"find\" | |
| 379 | ||
| 380 | See \"Note\" in the [[Recusive completion on subdirectories][section on subdirectories]]. | |
| 381 | ||
| 382 | Using \"locate\", you can enable the local database with a prefix argument. If the | |
| 383 | local database doesn't already exists, you will be prompted for its creation. | |
| 384 | If it exists and you want to refresh it, give it two prefix args. | |
| 385 | ||
| 386 | When using locate the helm-buffer remains empty until you type something. | |
| 387 | Regardless Helm uses the basename of the pattern entered in the helm-find-files | |
| 388 | session by default. Hitting `\\[next-history-element]' should just kick in the | |
| 389 | locate search with this pattern. If you want Helm to automatically do this, add | |
| 390 | `helm-source-locate' to `helm-sources-using-default-as-input'. | |
| 391 | ||
| 392 | **** Recursive completion on subdirectories | |
| 393 | ||
| 394 | Starting from the directory you are currently browsing, it is possible to have | |
| 395 | completion of all directories underneath. Say you are at \"/home/you/foo/\" and | |
| 396 | you want to go to \"/home/you/foo/bar/baz/somewhere/else\", simply type | |
| 397 | \"/home/you/foo/..else\" and hit `\\[helm-execute-persistent-action]' or enter | |
| 398 | the final \"/\". Helm will then list all possible directories under \"foo\" | |
| 399 | matching \"else\". | |
| 400 | ||
| 401 | Entering two spaces before \"else\" instead of two dots also works. | |
| 402 | ||
| 403 | Note: Completion on subdirectories uses \"locate\" as backend, you can configure | |
| 404 | the command with `helm-locate-recursive-dirs-command'. Because this completion | |
| 405 | uses an index, the directory tree displayed may be out-of-date and not reflect | |
| 406 | the latest change until you update the index (using \"updatedb\" for \"locate\"). | |
| 407 | ||
| 408 | If for some reason you cannot use an index, the \"find\" command from | |
| 409 | \"findutils\" can be used instead. It will be slower though. You need to pass | |
| 410 | the basedir as first argument of \"find\" and the subdir as the value for | |
| 411 | '-(i)regex' or '-(i)name' with the two format specs that are mandatory in | |
| 412 | `helm-locate-recursive-dirs-command'. | |
| 413 | ||
| 414 | Examples: | |
| 415 | - \"find %s -type d -name '*%s*'\" | |
| 416 | - \"find %s -type d -regex .*%s.*$\" | |
| 417 | ||
| 418 | *** Insert filename at point or complete filename at point | |
| 419 | ||
| 420 | On insertion (not on completion, i.e. there is nothing at point): | |
| 421 | ||
| 422 | - `\\[helm-ff-run-complete-fn-at-point]': insert absolute file name. | |
| 423 | - `\\[universal-argument] \\[helm-ff-run-complete-fn-at-point]': insert abbreviated file name. | |
| 424 | - `\\[universal-argument] \\[universal-argument] \\[helm-ff-run-complete-fn-at-point]': insert relative file name. | |
| 425 | ||
| 426 | On completion: | |
| 427 | ||
| 428 | - Target starts with \"~/\": insert abbreviate file name. | |
| 429 | - target starts with \"/\" or \"[a-z]:/\": insert full path. | |
| 430 | - Otherwise: insert relative file name. | |
| 431 | ||
| 432 | *** Use the wildcard to select multiple files | |
| 433 | ||
| 434 | Use of wilcard is supported to run an action over a set of files. | |
| 435 | ||
| 436 | Example: You can copy all the files with \".el\" extension by using \"*.el\" and | |
| 437 | then run copy action. | |
| 438 | ||
| 439 | Similarly, \"**.el\" (note the two stars) will recursively select all \".el\" | |
| 440 | files under the current directory. | |
| 441 | ||
| 442 | Note that when recursively copying files, you may have files with same name | |
| 443 | dispatched across different subdirectories, so when copying them in the same | |
| 444 | directory they will get overwritten. To avoid this Helm has a special action | |
| 445 | called \"backup files\" that has the same behavior as the command line \"cp -f | |
| 446 | --backup=numbered\": it allows you to copy many files with the same name from | |
| 447 | different subdirectories into one directory. Files with same name are renamed | |
| 448 | as follows: \"foo.txt.~1~\". Like with the --force option of cp, it is possible | |
| 449 | to backup files in current directory. | |
| 450 | ||
| 451 | This command is available only when `dired-async-mode' is active. | |
| 452 | ||
| 453 | When using an action that involves an external backend (e.g. grep), using \"**\" | |
| 454 | is not recommended (even thought it works fine) because it will be slower to | |
| 455 | select all the files. You are better off leaving the backend to do it, it will | |
| 456 | be faster. However, if you know you have not many files it is reasonable to use | |
| 457 | this, also using not recursive wilcard (e.g. \"*.el\") is perfectly fine for | |
| 458 | this. | |
| 459 | ||
| 460 | The \"**\" feature is active by default in the option `helm-file-globstar'. It | |
| 461 | is different from the Bash \"shopt globstar\" feature in that to list files with | |
| 462 | a named extension recursively you would write \"**.el\" whereas in Bash it would | |
| 463 | be \"**/*.el\". Directory selection with \"**/\" like Bash \"shopt globstar\" | |
| 464 | option is not supported yet. | |
| 465 | ||
| 466 | *** Query replace regexp on filenames | |
| 467 | ||
| 468 | Replace different parts of a file basename with something else. | |
| 469 | ||
| 470 | When calling this action you will be prompted twice as with | |
| 471 | `query-replace', first for the matching expression of the text to | |
| 472 | replace and second for the replacement text. Several facilities, | |
| 473 | however, are provided to make the two prompts more powerfull. | |
| 474 | ||
| 475 | **** Syntax of the first prompt | |
| 476 | ||
| 477 | In addition to simple regexps, these shortcuts are available: | |
| 478 | ||
| 479 | - Basename without extension => \"%.\" | |
| 480 | - Only extension => \".%\" | |
| 481 | - Substring => \"%:<from>:<to>\" | |
| 482 | - Whole basename => \"%\" | |
| 483 | ||
| 484 | **** Syntax of the second prompt | |
| 485 | ||
| 486 | In addition to a simple string to use as replacement, here is what you can use: | |
| 487 | ||
| 488 | - A placeholder refering to what you have selected in the first prompt: \"\\@\". | |
| 489 | ||
| 490 | After this placeholder you can use a search-and-replace syntax à-la sed: | |
| 491 | ||
| 492 | \"\\@/<regexp>/<replacement>/ | |
| 493 | ||
| 494 | You can select a substring from the string represented by the placeholder: | |
| 495 | ||
| 496 | \"\\@:<from>:<to>\" | |
| 497 | ||
| 498 | - A special character representing a number which is incremented: \"\\#\". | |
| 499 | ||
| 500 | - Shortcuts for `upcase', `downcase' and `capitalize' | |
| 501 | are available as`%u', `%d' and `%c' respectively. | |
| 502 | ||
| 503 | **** Examples | |
| 504 | ||
| 505 | ***** Recursively rename all files with \".JPG\" extension to \".jpg\" | |
| 506 | ||
| 507 | Use the `helm-file-globstar' feature described in [[Using wildcard to select multiple files][recursive globbing]] | |
| 508 | by entering \"**.JPG\" at the end of the Helm-find-files pattern, then hit | |
| 509 | \\<helm-map>\\[helm-ff-query-replace-on-filenames]: First \"JPG\", then \"jpg\" | |
| 510 | and hit `RET'. | |
| 511 | ||
| 512 | Alternatively you can enter \".%\" at the first prompt, then \"jpg\" and hit | |
| 513 | `RET'. Note that when using this instead of using \"JPG\" at the first prompt, | |
| 514 | all extensions will be renamed to \"jpg\" even if the extension of one of the | |
| 515 | files is, say, \"png\". If you want to keep the original extension you can use | |
| 516 | \"%d\" at the second prompt (downcase). | |
| 517 | ||
| 518 | ***** Batch-rename files from number 001 to 00x | |
| 519 | ||
| 520 | Use \"\\#\" inside the second prompt. | |
| 521 | ||
| 522 | Example 1: To rename the files | |
| 523 | ||
| 524 | foo.jpg | |
| 525 | bar.jpg | |
| 526 | baz.jpg | |
| 527 | ||
| 528 | to | |
| 529 | ||
| 530 | foo-001.jpg | |
| 531 | foo-002.jpg | |
| 532 | foo-003.jpg | |
| 533 | ||
| 534 | use \"%.\" as matching regexp and \"foo-\\#\" as replacement string. | |
| 535 | ||
| 536 | Example 2: To rename the files | |
| 537 | ||
| 538 | foo.jpg | |
| 539 | bar.jpg | |
| 540 | baz.jpg | |
| 541 | ||
| 542 | to | |
| 543 | ||
| 544 | foo-001.jpg | |
| 545 | bar-002.jpg | |
| 546 | baz-003.jpg | |
| 547 | ||
| 548 | use as matching regexp \"%.\" and as replacement string \"\\@-\\#\". | |
| 549 | ||
| 550 | ***** Replace a substring | |
| 551 | ||
| 552 | Use \"%:<from>:<to>\". | |
| 553 | ||
| 554 | Example: To rename files | |
| 555 | ||
| 556 | foo.jpg | |
| 557 | bar.jpg | |
| 558 | baz.jpg | |
| 559 | ||
| 560 | to | |
| 561 | ||
| 562 | fOo.jpg | |
| 563 | bAr.jpg | |
| 564 | bAz.jpg | |
| 565 | ||
| 566 | use as matching regexp \"%:1:2\" and as replacement string \"%u\" (upcase). | |
| 567 | ||
| 568 | Note that you \*cannot* use \"%.\" and \".%\" along with substring replacement. | |
| 569 | ||
| 570 | ***** Modify the string from the placeholder (\\@) | |
| 571 | ||
| 572 | - By substring, i.e. only using the substring of the placeholder: \"\\@:<from>:<to>\". | |
| 573 | The length of placeholder is used for <to> when unspecified. | |
| 574 | ||
| 575 | Example 1: \"\\@:0:2\" replaces from the beginning to the second char of the placeholder. | |
| 576 | ||
| 577 | Example 2: \\@:2: replaces from the second char of the placeholder to the end. | |
| 578 | ||
| 579 | - By search-and-replace: \"\\@/<regexp>/<replacement>/\". | |
| 580 | ||
| 581 | Incremental replacement is also handled in <replacement>. | |
| 582 | ||
| 583 | Example 3: \"\\@/foo/bar/\" replaces \"foo\" by \"bar\" in the placeholder. | |
| 584 | ||
| 585 | Example 4: \"\\@/foo/-\\#/\" replaces \"foo\" in the placeholder by 001, 002, etc. | |
| 586 | ||
| 587 | ***** Clash in replacements (avoid overwriting files) | |
| 588 | ||
| 589 | When performing any of these replacement operations you may end up with same | |
| 590 | names as replacement. In such cases Helm numbers the file that would otherwise | |
| 591 | overwritten. For instance, should you remove the \"-m<n>\" part from the files | |
| 592 | \"emacs-m1.txt\", \"emacs-m2.txt\" and \"emacs-m3.txt\" you would end up with | |
| 593 | three files named \"emacs.txt\", the second renaming overwriting first file, and | |
| 594 | the third renaming overwriting second file and so on. Instead Helm will | |
| 595 | automatically rename the second and third files as \"emacs(1).txt\" and | |
| 596 | \"emacs(2).txt\" respectively. | |
| 597 | ||
| 598 | ***** Query-replace on filenames vs. serial-rename action | |
| 599 | ||
| 600 | Unlike the [[Serial renaming][serial rename]] actions, the files renamed with | |
| 601 | the query-replace action stay in their initial directory and are not moved to | |
| 602 | the current directory. As such, using \"\\#\" to serial-rename files only makes | |
| 603 | sense for files inside the same directory. It even keeps renaming files | |
| 604 | with an incremental number in the next directories. | |
| 605 | ||
| 606 | *** Serial-rename | |
| 607 | ||
| 608 | You can use the serial-rename actions to rename, copy or symlink marked files to | |
| 609 | a specific directory or in the current directory with all the files numbered | |
| 610 | incrementally. | |
| 611 | ||
| 612 | - Serial-rename by renaming: | |
| 613 | Rename all marked files with incremental numbering to a specific directory. | |
| 614 | ||
| 615 | - Serial-rename by copying: | |
| 616 | Copy all marked files with incremental numbering to a specific directory. | |
| 617 | ||
| 618 | - Serial-rename by symlinking: | |
| 619 | Symlink all marked files with incremental numbering to a specific directory. | |
| 620 | ||
| 621 | *** Edit marked files in a dired buffer | |
| 622 | ||
| 623 | You can open a dired buffer containing only marked files with `\\<helm-find-files-map>\\[helm-ff-run-marked-files-in-dired]'. | |
| 624 | With a prefix argument you can open this same dired buffer in wdired mode for | |
| 625 | editing. Note that wildcards are supported as well, so you can use e.g. | |
| 626 | \"*.txt\" to select all \".txt\" files in the current directory or \"**.txt\" to | |
| 627 | select all files recursively from the current directory. | |
| 628 | See [[Use the wildcard to select multiple files]] section above. | |
| 629 | ||
| 630 | *** Defining default target directory for copying, renaming, etc | |
| 631 | ||
| 632 | You can customize `helm-dwim-target' to behave differently depending on the | |
| 633 | windows open in the current frame. Default is to provide completion on all | |
| 634 | directories associated to each window. | |
| 635 | ||
| 636 | *** Copying and renaming asynchronously | |
| 637 | ||
| 638 | If you have the async library installed (if you got Helm from MELPA you do), you | |
| 639 | can use it for copying/renaming files by enabling `dired-async-mode'. | |
| 640 | ||
| 641 | Note that even when async is enabled, running a copy/rename action with a prefix | |
| 642 | argument will execute action synchronously. Moreover it will follow the first | |
| 643 | file of the marked files in its destination directory. | |
| 644 | ||
| 645 | When `dired-async-mode' is enabled, an additional action named \"Backup files\" | |
| 646 | will be available. (Such command is not natively available in Emacs). | |
| 647 | See [[Use the wildcard to select multiple files]] for details. | |
| 648 | ||
| 649 | *** Bookmark the `helm-find-files' session | |
| 650 | ||
| 651 | You can bookmark the `helm-find-files' session with `\\[helm-ff-bookmark-set]'. | |
| 652 | You can later retrieve these bookmarks by calling `helm-filtered-bookmarks' | |
| 653 | or, from the current `helm-find-files' session, by hitting `\\[helm-find-files-toggle-to-bookmark]'. | |
| 654 | ||
| 655 | *** Grep files from `helm-find-files' | |
| 656 | ||
| 657 | You can grep individual files from `helm-find-files' by using | |
| 658 | \`\\<helm-find-files-map>\\[helm-ff-run-grep]'. This same command can also | |
| 659 | recursively grep files from the current directory when called with a prefix | |
| 660 | argument. In this case you will be prompted for the file extensions to use | |
| 661 | \(grep backend) or the types of files to use (ack-grep backend). See the | |
| 662 | `helm-grep-default-command' documentation to set this up. For compressed files | |
| 663 | or archives, use zgrep with \`\\<helm-find-files-map>\\[helm-ff-run-zgrep]'. | |
| 664 | ||
| 665 | 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]' | |
| 666 | that are much faster than using `\\<helm-find-files-map>\\[helm-ff-run-grep]' with a prefix argument. | |
| 667 | See `helm-grep-ag-command' and `helm-grep-git-grep-command' to set this up. | |
| 668 | ||
| 669 | You can also use \"id-utils\"' GID with \`\\<helm-find-files-map>\\[helm-ff-run-gid]' | |
| 670 | by creating an ID index file with the \"mkid\" shell command. | |
| 671 | ||
| 672 | All those grep commands use the symbol at point as the default pattern. | |
| 673 | Note that default is different from input (nothing is added to the prompt until | |
| 674 | you hit `\\[next-history-element]'). | |
| 675 | ||
| 676 | **** Grepping on remote files | |
| 677 | ||
| 678 | On remote files grep is not well supported by TRAMP unless you suspend updates before | |
| 679 | entering the pattern and re-enable it once your pattern is ready. | |
| 680 | To toggle suspend-update, use `\\<helm-map>\\[helm-toggle-suspend-update]'. | |
| 681 | ||
| 682 | *** Setting up aliases in Eshell allows you to set up powerful customized commands | |
| 683 | ||
| 684 | Adding Eshell aliases to your `eshell-aliases-file' or using the | |
| 685 | `alias' command from Eshell allows you to create personalized | |
| 686 | commands not available in `helm-find-files' actions and use them | |
| 687 | from `\\<helm-find-files-map>\\[helm-ff-run-eshell-command-on-file]'. | |
| 688 | ||
| 689 | Example: You want a command to uncompress some \"*.tar.gz\" files from `helm-find-files': | |
| 690 | ||
| 691 | 1) Create an Eshell alias named, say, \"untargz\" with the command | |
| 692 | \"alias untargz tar zxvf $*\". | |
| 693 | ||
| 694 | 2) Now from `helm-find-files' select the \"*.tar.gz\" file (you can also | |
| 695 | mark files if needed) and hit `\\<helm-find-files-map>\\[helm-ff-run-eshell-command-on-file]'. | |
| 696 | ||
| 697 | Note: When using marked files with this, the meaning of the prefix argument is | |
| 698 | quite subtle. Say you have \"foo\", \"bar\" and \"baz\" marked; when you run | |
| 699 | the alias command `example' on these files with no prefix argument it will run | |
| 700 | `example' sequentially on each file: | |
| 701 | ||
| 702 | $ example foo | |
| 703 | $ example bar | |
| 704 | $ example baz | |
| 705 | ||
| 706 | With a prefix argument however it will apply `example' on all files at once: | |
| 707 | ||
| 708 | $ example foo bar baz | |
| 709 | ||
| 710 | Of course the alias command should support this. | |
| 711 | ||
| 712 | *** Using TRAMP with `helm-find-files' to read remote directories | |
| 713 | ||
| 714 | `helm-find-files' works fine with TRAMP despite some limitations. | |
| 715 | ||
| 716 | - Grepping files is not very well supported when used incrementally. | |
| 717 | See [[Grepping on remote files]]. | |
| 718 | ||
| 719 | - Locate does not work on remote directories. | |
| 720 | ||
| 721 | **** A TRAMP syntax crash course | |
| 722 | ||
| 723 | Please refer to TRAMP's documentation for more details. | |
| 724 | ||
| 725 | - Connect to host 192.168.0.4 as user \"foo\": | |
| 726 | ||
| 727 | /scp:192.168.0.4@foo: | |
| 728 | ||
| 729 | - Connect to host 192.168.0.4 as user \"foo\" on port 2222: | |
| 730 | ||
| 731 | /scp:192.168.0.4@foo#2222: | |
| 732 | ||
| 733 | - Connect to host 192.168.0.4 as root using multihops syntax: | |
| 734 | ||
| 735 | /ssh:192.168.0.4@foo|sudo:192.168.0.4: | |
| 736 | ||
| 737 | Note: You can also use `tramp-default-proxies-alist' when connecting often to | |
| 738 | the same hosts. | |
| 739 | ||
| 740 | As a rule of thumb, prefer the scp method unless using multihops (which only | |
| 741 | works with the ssh method), especially when copying large files. | |
| 742 | ||
| 743 | You need to hit `C-j' once on top of a directory on the first connection | |
| 744 | to complete the pattern in the minibuffer. | |
| 745 | ||
| 746 | **** Display color for directories, symlinks etc... with tramp | |
| 747 | ||
| 748 | Starting at helm version 2.9.7 it is somewhat possible to | |
| 749 | colorize fnames by listing files without loosing performances with | |
| 750 | external commands (ls and awk) if your system is compatible. | |
| 751 | For this you can use `helm-list-dir-external' as value | |
| 752 | for `helm-list-directory-function'. | |
| 753 | ||
| 754 | See `helm-list-directory-function' documentation for more infos. | |
| 755 | ||
| 756 | **** Completing host | |
| 757 | ||
| 758 | As soon as you enter the first \":\" after method e.g =/scp:= you will | |
| 759 | have some completion about previously used hosts or from your =~/.ssh/config= | |
| 760 | file, hitting `\\[helm-execute-persistent-action]' or `right' on a candidate will insert this host in minibuffer | |
| 761 | without addind the ending \":\", second hit insert the last \":\". | |
| 762 | As soon the last \":\" is entered TRAMP will kick in and you should see the list | |
| 763 | of candidates soon after. | |
| 764 | ||
| 765 | When connection fails, be sure to delete your TRAMP connection with M-x | |
| 766 | `helm-delete-tramp-connection' before retrying. | |
| 767 | ||
| 768 | **** Editing local files as root | |
| 769 | ||
| 770 | Use the sudo method: | |
| 771 | ||
| 772 | \"/sudo:host:\" or simply \"/sudo::\". | |
| 773 | ||
| 774 | *** Attach files to a mail buffer (message-mode) | |
| 775 | ||
| 776 | If you are in a `message-mode' or `mail-mode' buffer, that action will appear | |
| 777 | in action menu, otherwise it is available at any time with \\<helm-find-files-map>\\[helm-ff-run-mail-attach-files]. | |
| 778 | It behaves as follows: | |
| 779 | ||
| 780 | - If you are in a (mail or message) buffer, files are attached there. | |
| 781 | ||
| 782 | - If you are not in a mail buffer but one or more mail buffers exist, you are | |
| 783 | prompted to attach files to one of these mail buffers. | |
| 784 | ||
| 785 | - If you are not in a mail buffer and no mail buffer exists, | |
| 786 | a new mail buffer is created with the attached files in it. | |
| 787 | ||
| 788 | *** Open files in separate windows | |
| 789 | ||
| 790 | When [[Marked candidates][marking]] multiple files or using [[Use the wildcard to select multiple files][wildcard]], helm allow opening all | |
| 791 | this files in separate windows using an horizontal layout or a | |
| 792 | vertical layout if you used a prefix arg, when no more windows can be | |
| 793 | displayed in frame, next files are opened in background without being | |
| 794 | displayed. When using \\<helm-find-files-map>\\[helm-ff-run-switch-other-window] the current | |
| 795 | buffer is kept and files are displayed next to it with same behavior as above. | |
| 796 | When using two prefix args, files are opened in background without beeing displayed. | |
| 797 | ||
| 798 | *** Expand archives as directories in a avfs directory | |
| 799 | ||
| 800 | If you have mounted your filesystem with mountavfs, | |
| 801 | you can expand archives in the \"~/.avfs\" directory with \\<helm-map>\\[helm-execute-persistent-action]. | |
| 802 | ||
| 803 | *** Tramp archive support (emacs-27+ only) | |
| 804 | ||
| 805 | If your emacs have library tramp-archive.el, you can browse the | |
| 806 | content of archives with emacs and BTW helm-find-files. However this beeing | |
| 807 | experimental and not very fast, helm doesn't provide an automatic | |
| 808 | expansion and detection of archives, you will have to add the final / | |
| 809 | manually and may have to force update (\\<helm-map>\\[helm-refresh]) | |
| 810 | or remove and add again the final / until tramp finish decompressing archive. | |
| 811 | ||
| 812 | *** Touch files | |
| 813 | ||
| 814 | In the completion buffer, you can choose the default which is the current-time, it is | |
| 815 | the first candidate or the timestamp of one of the selected files. | |
| 816 | If you need to use something else, use \\<helm-map>\\[next-history-element] and edit | |
| 817 | the date in minibuffer. | |
| 818 | It is also a way to quickly create a new file without opening a buffer, saving it | |
| 819 | and killing it. | |
| 820 | To touch more than one new file, separate you filenames with a comma (\",\"). | |
| 821 | If one wants to create (touch) a new file with comma inside the name use a prefix arg, | |
| 822 | this will prevent splitting the name and create multiple files. | |
| 823 | ||
| 824 | *** Delete files | |
| 825 | ||
| 826 | You can delete files without quitting helm with | |
| 827 | `\\<helm-find-files-map>\\[helm-ff-persistent-delete]' or delete files and quit helm with `\\[helm-ff-run-delete-file]'. | |
| 828 | ||
| 829 | In the second method you can choose to | |
| 830 | make this command asynchronous by customizing | |
| 831 | \`helm-ff-delete-files-function'. | |
| 832 | ||
| 833 | _WARNING_: When deleting files asynchronously you will NOT be | |
| 834 | WARNED if directories are not empty, that's mean non empty directories will | |
| 835 | be deleted in background without asking. | |
| 836 | ||
| 837 | A good compromise is to trash your files | |
| 838 | when using asynchronous method (see [[Trashing files][Trashing files]]). | |
| 839 | ||
| 840 | When choosing synchronous delete, you can allow recursive | |
| 841 | deletion of directories with `helm-ff-allow-recursive-deletes'. | |
| 842 | Note that when trashing (synchronous) you are not asked for recursive deletion. | |
| 843 | ||
| 844 | Note that `helm-ff-allow-recursive-deletes' have no effect when | |
| 845 | deleting asynchronously. | |
| 846 | ||
| 847 | First method (persistent delete) is always synchronous. | |
| 848 | ||
| 849 | Note that when a prefix arg is given, trashing behavior is inversed. | |
| 850 | See [[Trashing files][Trashing files]]. | |
| 851 | ||
| 852 | **** Trashing files | |
| 853 | ||
| 854 | If you want to trash your files instead of deleting them you can | |
| 855 | set `delete-by-moving-to-trash' to non nil, like this your files | |
| 856 | will be moved to trash instead of beeing deleted. | |
| 857 | ||
| 858 | You can reverse at any time the behavior of `delete-by-moving-to-trash' by using | |
| 859 | a prefix arg with any of the delete files command. | |
| 860 | ||
| 861 | On GNULinux distribution, when navigating to a Trash directory you | |
| 862 | can restore any file in ..Trash/files directory with the 'Restore | |
| 863 | from trash' action you will find in action menu (needs the | |
| 864 | trash-cli package installed). | |
| 865 | You can as well delete files from Trash directories with the 'delete files from trash' | |
| 866 | action. | |
| 867 | ||
| 868 | Tip: Navigate to your Trash/files directories with `helm-find-files' and set a bookmark | |
| 869 | there with \\<helm-find-files-map>\\[helm-ff-bookmark-set] for fast access to Trash. | |
| 870 | ||
| 871 | _WARNING:_ | |
| 872 | ||
| 873 | If you have an ENV var XDG_DATA_HOME in your .profile or .bash_profile | |
| 874 | and this var is set to something like $HOME/.local/share (like preconized) | |
| 875 | `move-file-to-trash' may try to create $HOME/.local/share/Trash (literally) | |
| 876 | and its subdirs in the directory where you are actually trying to trash files. | |
| 877 | because `move-file-to-trash' is interpreting XDG_DATA_HOME literally instead | |
| 878 | of evaling its value (with `substitute-in-file-name'). | |
| 879 | ||
| 880 | ***** Trashing remote files with tramp | |
| 881 | ||
| 882 | Trashing remote files (or local files with sudo method) is disabled by default | |
| 883 | because tramp is requiring the 'trash' command to be installed, if you want to | |
| 884 | trash your remote files, customize `helm-trash-remote-files'. | |
| 885 | The package on most GNU/Linux based distributions is trash-cli, it is available [[https://github.com/andreafrancia/trash-cli][here]]. | |
| 886 | ||
| 887 | NOTE: | |
| 888 | When deleting your files with sudo method, your trashed files will not be listed | |
| 889 | with trash-list until you log in as root. | |
| 890 | ||
| 891 | ** Commands | |
| 892 | \\<helm-find-files-map> | |
| 893 | \\[helm-ff-run-locate]\t\tRun `locate' (`\\[universal-argument]' to specify locate database, `M-n' to insert basename of candidate). | |
| 894 | \\[helm-ff-run-browse-project]\t\tBrowse project (`\\[universal-argument]' to recurse, `\\[universal-argument] \\[universal-argument]' to recurse and refresh database). | |
| 895 | \\[helm-ff-run-find-sh-command]\t\tRun `find' shell command from this directory. | |
| 896 | \\[helm-ff-run-grep]\t\tRun Grep (`\\[universal-argument]' to recurse). | |
| 897 | \\[helm-ff-run-pdfgrep]\t\tRun Pdfgrep on marked files. | |
| 898 | \\[helm-ff-run-zgrep]\t\tRun zgrep (`\\[universal-argument]' to recurse). | |
| 899 | \\[helm-ff-run-grep-ag]\t\tRun AG grep on current directory. | |
| 900 | \\[helm-ff-run-git-grep]\t\tRun git-grep on current directory. | |
| 901 | \\[helm-ff-run-gid]\t\tRun gid (id-utils). | |
| 902 | \\[helm-ff-run-etags]\t\tRun Etags (`\\[universal-argument]' to use thing-at-point, `\\[universal-argument] \\[universal-argument]' to reload cache). | |
| 903 | \\[helm-ff-run-rename-file]\t\tRename Files (`\\[universal-argument]' to follow). | |
| 904 | \\[helm-ff-run-query-replace-fnames-on-marked]\t\tQuery replace on marked files. | |
| 905 | \\[helm-ff-run-copy-file]\t\tCopy Files (`\\[universal-argument]' to follow). | |
| 906 | \\[helm-ff-run-byte-compile-file]\t\tByte Compile Files (`\\[universal-argument]' to load). | |
| 907 | \\[helm-ff-run-load-file]\t\tLoad Files. | |
| 908 | \\[helm-ff-run-symlink-file]\t\tSymlink Files. | |
| 909 | \\[helm-ff-run-hardlink-file]\t\tHardlink files. | |
| 910 | \\[helm-ff-run-relsymlink-file]\t\tRelative symlink Files. | |
| 911 | \\[helm-ff-run-delete-file]\t\tDelete Files. | |
| 912 | \\[helm-ff-run-touch-files]\t\tTouch files. | |
| 913 | \\[helm-ff-run-kill-buffer-persistent]\t\tKill buffer candidate without leaving Helm. | |
| 914 | \\[helm-ff-persistent-delete]\t\tDelete file without leaving Helm. | |
| 915 | \\[helm-ff-run-switch-to-eshell]\t\tSwitch to Eshell. | |
| 916 | \\[helm-ff-run-eshell-command-on-file]\t\tEshell command on file (`\\[universal-argument]' to apply on marked files, otherwise treat them sequentially). | |
| 917 | \\[helm-ff-run-ediff-file]\t\tEdiff file. | |
| 918 | \\[helm-ff-run-ediff-merge-file]\t\tEdiff merge file. | |
| 919 | \\[helm-ff-run-complete-fn-at-point]\t\tComplete file name at point. | |
| 920 | \\[helm-ff-run-switch-other-window]\t\tSwitch to other window. | |
| 921 | \\[helm-ff-run-switch-other-frame]\t\tSwitch to other frame. | |
| 922 | \\[helm-ff-run-open-file-externally]\t\tOpen file with external program (`\\[universal-argument]' to choose). | |
| 923 | \\[helm-ff-run-preview-file-externally]\t\tPreview file with external program. | |
| 924 | \\[helm-ff-run-open-file-with-default-tool]\t\tOpen file externally with default tool. | |
| 925 | \\[helm-ff-rotate-left-persistent]\t\tRotate image left. | |
| 926 | \\[helm-ff-rotate-right-persistent]\t\tRotate image right. | |
| 927 | \\[helm-find-files-up-one-level]\t\tGo to parent directory. | |
| 928 | \\[helm-find-files-history]\t\tSwitch to the visited-directory history. | |
| 929 | \\[helm-ff-file-name-history]\t\tSwitch to file name history. | |
| 930 | \\[helm-ff-properties-persistent]\t\tShow file properties in a tooltip. | |
| 931 | \\[helm-mark-all]\t\tMark all visible candidates. | |
| 932 | \\[helm-ff-run-toggle-auto-update]\t\tToggle auto-expansion of directories. | |
| 933 | \\[helm-unmark-all]\t\tUnmark all candidates, visible and invisible ones. | |
| 934 | \\[helm-ff-run-gnus-attach-files]\t\tGnus' attach files to message buffer. | |
| 935 | \\[helm-ff-run-print-file]\t\tPrint file, (`\\[universal-argument]' to refresh printer list). | |
| 936 | \\[helm-enlarge-window]\t\tEnlarge Helm window. | |
| 937 | \\[helm-narrow-window]\t\tNarrow Helm window. | |
| 938 | \\[helm-ff-run-toggle-basename]\t\tToggle basename/fullpath. | |
| 939 | \\[helm-ff-run-find-file-as-root]\t\tFind file as root. | |
| 940 | \\[helm-ff-run-find-alternate-file]\t\tFind alternate file. | |
| 941 | \\[helm-ff-run-insert-org-link]\t\tInsert org link. | |
| 942 | \\[helm-ff-bookmark-set]\t\tSet bookmark to current directory. | |
| 943 | \\[helm-find-files-toggle-to-bookmark]\t\tJump to bookmark list.") | |
| 944 | ||
| 945 | ;;; Help for `helm-read-file-name' | |
| 946 | ;; | |
| 947 | ;; | |
| 948 | (defun helm-read-file-name-help-message () | |
| 949 | (let ((name (if helm-alive-p | |
| 950 | (assoc-default 'name (helm-get-current-source)) | |
| 951 | "generic"))) | |
| 952 | (format | |
| 953 | "* Helm `%s' read file name completion | |
| 954 | ||
| 955 | This is `%s' read file name completion that have been \"helmized\" | |
| 956 | because you have enabled [[Helm mode][helm-mode]]'. | |
| 957 | Don't confuse this with `helm-find-files' which is a native helm command, | |
| 958 | see [[Helm functions vs helmized emacs functions]]. | |
| 959 | ||
| 960 | ** Tips | |
| 961 | ||
| 962 | *** Navigation | |
| 963 | ||
| 964 | **** Enter `~/' at end of pattern to quickly reach home directory | |
| 965 | ||
| 966 | **** Enter `/' at end of pattern to quickly reach the file system root | |
| 967 | ||
| 968 | **** Enter `./' at end of pattern to quickly reach `default-directory' | |
| 969 | ||
| 970 | \(As per its value at the beginning of the session.) | |
| 971 | ||
| 972 | If you already are in the `default-directory' this will move the cursor to the top. | |
| 973 | ||
| 974 | **** Enter `../' at end of pattern will reach upper directory, moving cursor on top | |
| 975 | ||
| 976 | This is different from using `\\[helm-find-files-up-one-level]' in that it moves | |
| 977 | the cursor to the top instead of remaining on the previous subdir name. | |
| 978 | ||
| 979 | **** You can complete with partial basename | |
| 980 | ||
| 981 | It starts from the third character of the pattern. | |
| 982 | ||
| 983 | For instance \"fob\" or \"fbr\" will complete \"foobar\" but \"fb\" needs a | |
| 984 | third character in order to complete it. | |
| 985 | ||
| 986 | *** Persistent actions | |
| 987 | ||
| 988 | By default `helm-read-file-name' uses the persistent actions of `helm-find-files'. | |
| 989 | ||
| 990 | **** Use `\\[universal-argument] \\<helm-map>\\[helm-execute-persistent-action]' to display an image | |
| 991 | ||
| 992 | **** `\\<helm-map>\\[helm-execute-persistent-action]' on a filename will expand to this filename in Helm-buffer | |
| 993 | ||
| 994 | Second hit displays the buffer filename. | |
| 995 | Third hit kills the buffer filename. | |
| 996 | Note: `\\[universal-argument] \\<helm-map>\\[helm-execute-persistent-action]' displays the buffer directly. | |
| 997 | ||
| 998 | **** Browse images directories with `helm-follow-mode' and navigate up/down | |
| 999 | ||
| 1000 | *** Delete characters backward | |
| 1001 | ||
| 1002 | When you want to delete characters backward, e.g. to create a new file or directory, | |
| 1003 | auto-update may come in the way when it keeps updating to an existent directory. | |
| 1004 | In that case, type `C-<backspace>' and then `<backspace>'. | |
| 1005 | This should not be needed when copying/renaming files because autoupdate is disabled | |
| 1006 | by default in that case. | |
| 1007 | ||
| 1008 | Note: On a terminal, the default binding `C-<backspace>' may not work. | |
| 1009 | In this case use `C-c <backspace>'. | |
| 1010 | ||
| 1011 | *** Create new directories and files | |
| 1012 | ||
| 1013 | **** You can create a new directory and a new file at the same time | |
| 1014 | ||
| 1015 | Simply write the path in prompt and press `RET', e.g. | |
| 1016 | \"~/new/newnew/newnewnew/my_newfile.txt\". | |
| 1017 | ||
| 1018 | **** To create a new directory, append a \"/\" at to the new name and press `RET' | |
| 1019 | ||
| 1020 | **** To create a new file, enter a filename not ending with \"/\" | |
| 1021 | ||
| 1022 | File and directory creation works only with some commands (e.g. `find-file') | |
| 1023 | and it will not work with others where it is not intended to return a file or | |
| 1024 | a directory \(e.g `list-directory'). | |
| 1025 | ||
| 1026 | *** Exiting minibuffer with empty string | |
| 1027 | ||
| 1028 | You can exit minibuffer with empty string with \\<helm-read-file--map>\\[helm-cr-empty-string]. | |
| 1029 | It is useful when some commands are prompting continuously until you enter an empty prompt. | |
| 1030 | ||
| 1031 | ** Commands | |
| 1032 | \\<helm-read-file-map> | |
| 1033 | \\[helm-find-files-up-one-level]\t\tGo to parent directory. | |
| 1034 | \\[helm-ff-run-toggle-auto-update]\t\tToggle auto-expansion of directories. | |
| 1035 | \\[helm-ff-run-toggle-basename]\t\tToggle basename. | |
| 1036 | \\[helm-ff-file-name-history]\t\tFile name history. | |
| 1037 | C/\\[helm-cr-empty-string]\t\tReturn empty string unless `must-match' is non-nil. | |
| 1038 | \\[helm-next-source]\t\tGo to next source. | |
| 1039 | \\[helm-previous-source]\t\tGo to previous source." | |
| 1040 | name name))) | |
| 1041 | ||
| 1042 | ;;; Generic file help - Used by locate. | |
| 1043 | ;; | |
| 1044 | ;; | |
| 1045 | (defvar helm-generic-file-help-message | |
| 1046 | "* Helm Generic files | |
| 1047 | ||
| 1048 | ** Tips | |
| 1049 | ||
| 1050 | *** Locate | |
| 1051 | ||
| 1052 | You can append to the search pattern any of the locate command line options, | |
| 1053 | e.g. -b, -e, -n <number>, etc. See the locate(1) man page for more details. | |
| 1054 | ||
| 1055 | Some other sources (at the moment \"recentf\" and \"file in current directory\") | |
| 1056 | support the -b flag for compatibility with locate when they are used with it. | |
| 1057 | ||
| 1058 | When you enable fuzzy matching on locate with `helm-locate-fuzzy-match', the | |
| 1059 | search will be performed on basename only for efficiency (so don't add \"-b\" at | |
| 1060 | prompt). As soon as you separate the patterns with spaces, fuzzy matching will | |
| 1061 | be disabled and search will be done on the full filename. Note that in | |
| 1062 | multi-match, fuzzy is completely disabled, which means that each pattern is a | |
| 1063 | match regexp (i.e. \"helm\" will match \"helm\" but \"hlm\" will \*not* match | |
| 1064 | \"helm\"). | |
| 1065 | ||
| 1066 | *** Browse project | |
| 1067 | ||
| 1068 | When the current directory is not under version control, don't forget to refresh | |
| 1069 | the cache when files have been added/removed in the directory. | |
| 1070 | ||
| 1071 | *** Find command | |
| 1072 | ||
| 1073 | Recursively search files using the \"find\" shell command. | |
| 1074 | ||
| 1075 | Candidates are all filenames that match all given globbing patterns. This | |
| 1076 | respects the options `helm-case-fold-search' and | |
| 1077 | `helm-findutils-search-full-path'. | |
| 1078 | ||
| 1079 | You can pass arbitrary \"find\" options directly after a \"*\" separator. | |
| 1080 | For example, this would find all files matching \"book\" that are larger | |
| 1081 | than 1 megabyte: | |
| 1082 | ||
| 1083 | book * -size +1M | |
| 1084 | ||
| 1085 | ** Commands | |
| 1086 | \\<helm-generic-files-map> | |
| 1087 | \\[helm-ff-run-toggle-basename]\t\tToggle basename. | |
| 1088 | \\[helm-ff-run-grep]\t\tRun grep (`\\[universal-argument]' to recurse). | |
| 1089 | \\[helm-ff-run-zgrep]\t\tRun zgrep. | |
| 1090 | \\[helm-ff-run-gid]\t\tRun GID (id-utils). | |
| 1091 | \\[helm-ff-run-pdfgrep]\t\tRun PDFgrep on marked files. | |
| 1092 | \\[helm-ff-run-copy-file]\t\tCopy file(s) | |
| 1093 | \\[helm-ff-run-rename-file]\t\tRename file(s). | |
| 1094 | \\[helm-ff-run-symlink-file]\t\tSymlink file(s). | |
| 1095 | \\[helm-ff-run-hardlink-file]\t\tHardlink file(s). | |
| 1096 | \\[helm-ff-run-delete-file]\t\tDelete file(s). | |
| 1097 | \\[helm-ff-run-byte-compile-file]\t\tByte compile Elisp file(s) (`\\[universal-argument]' to load). | |
| 1098 | \\[helm-ff-run-load-file]\t\tLoad Elisp file(s). | |
| 1099 | \\[helm-ff-run-ediff-file]\t\tEdiff file. | |
| 1100 | \\[helm-ff-run-ediff-merge-file]\t\tEdiff-merge file. | |
| 1101 | \\[helm-ff-run-switch-other-window]\t\tSwitch to other window. | |
| 1102 | \\[helm-ff-properties-persistent]\t\tShow file properties. | |
| 1103 | \\[helm-ff-run-etags]\t\tRun etags (`\\[universal-argument]' to use tap, `\\[universal-argument] \\[universal-argument]' to reload the database). | |
| 1104 | \\[helm-yank-text-at-point]\t\tYank text at point. | |
| 1105 | \\[helm-ff-run-open-file-externally]\t\tOpen file with external program (`\\[universal-argument]' to choose). | |
| 1106 | \\[helm-ff-run-open-file-with-default-tool]\t\tOpen file externally with default tool. | |
| 1107 | \\[helm-ff-run-insert-org-link]\t\tInsert org link.") | |
| 1108 | ||
| 1109 | ;;; Grep help | |
| 1110 | ;; | |
| 1111 | ;; | |
| 1112 | (defvar helm-grep-help-message | |
| 1113 | "* Helm Grep | |
| 1114 | ||
| 1115 | ** Tips | |
| 1116 | ||
| 1117 | *** Use a prefix argument to grep recursively | |
| 1118 | ||
| 1119 | With Helm supporting git-grep and AG however, you are better off using one of | |
| 1120 | them for recursive searches. | |
| 1121 | ||
| 1122 | *** You can use wild cards when selecting files (e.g. \"*.el\") | |
| 1123 | ||
| 1124 | *** You can grep in many different directories by marking files or using wild cards | |
| 1125 | ||
| 1126 | *** You can save the result in a `helm-grep-mode' buffer | |
| 1127 | ||
| 1128 | See [[Commands][commands]] below. | |
| 1129 | ||
| 1130 | Once in that buffer you can use \"emacs-wgrep\" (external package not bundled with Helm) | |
| 1131 | to edit your changes. | |
| 1132 | ||
| 1133 | *** Helm-grep supports multi-matching | |
| 1134 | ||
| 1135 | \(Starting from version 1.9.4.) | |
| 1136 | ||
| 1137 | Simply add a space between each pattern as for most Helm commands. | |
| 1138 | ||
| 1139 | *** See full path of selected candidate | |
| 1140 | ||
| 1141 | Add (helm-popup-tip-mode 1) in your init file or enable it interactively with | |
| 1142 | M-x helm-popup-tip-mode. | |
| 1143 | ||
| 1144 | *** Open file in other window | |
| 1145 | ||
| 1146 | The command \\<helm-grep-map>\\[helm-grep-run-other-window-action] allow you to open file | |
| 1147 | in other window horizontally or vertically if a prefix arg is supplied. | |
| 1148 | ||
| 1149 | *** Performance over TRAMP | |
| 1150 | ||
| 1151 | Grepping works but it is badly supported as TRAMP doesn't support multiple | |
| 1152 | processes running in a short delay (less than 5s) among other things. | |
| 1153 | ||
| 1154 | Helm uses a special hook to suspend the process automatically while you are | |
| 1155 | typing. Even if Helm handles this automatically by delaying each process by 5s, | |
| 1156 | you are adviced to this manually by hitting `\\<helm-map>\\[helm-toggle-suspend-update]' (suspend process) before | |
| 1157 | typing, and hit again `\\<helm-map>\\[helm-toggle-suspend-update]' when the regexp is ready to send to the remote | |
| 1158 | process. For simple regexps, there should be no need for this. | |
| 1159 | ||
| 1160 | Another solution is to not use TRAMP at all and mount your remote file system via | |
| 1161 | SSHFS. | |
| 1162 | ||
| 1163 | * Helm GID | |
| 1164 | ||
| 1165 | ** Tips | |
| 1166 | ||
| 1167 | Helm-GID reads the database created with the `mkid' command from id-utils. | |
| 1168 | The name of the database file can be customized with `helm-gid-db-file-name', it | |
| 1169 | is usually \"ID\". | |
| 1170 | ||
| 1171 | Helm-GID use the symbol at point as default-input. This command is also | |
| 1172 | accessible from `helm-find-files' which allow you to navigate to another | |
| 1173 | directory to consult its database. | |
| 1174 | ||
| 1175 | Note: Helm-GID supports multi-matches but only the last pattern entered will be | |
| 1176 | highlighted since there is no ~--color~-like option in GID itself. | |
| 1177 | ||
| 1178 | * Helm AG | |
| 1179 | ||
| 1180 | ** Tips | |
| 1181 | ||
| 1182 | Helm-AG is different from grep or ack-grep in that it works on a directory and | |
| 1183 | not on a list of files. | |
| 1184 | ||
| 1185 | You can ignore files and directories with a \".agignore\" file, local to a | |
| 1186 | directory or global when placed in the home directory. \(See the AG man page for | |
| 1187 | more details.) That file follows the same syntax as `helm-grep-ignored-files' | |
| 1188 | and `helm-grep-ignored-directories'. | |
| 1189 | ||
| 1190 | As always you can access Helm AG from `helm-find-files'. | |
| 1191 | ||
| 1192 | Starting with version 0.30, AG accepts one or more TYPE arguments on its command | |
| 1193 | line. Helm provides completion on these TYPE arguments when available with your | |
| 1194 | AG version. Use a prefix argument when starting a Helm-AG session to enable this | |
| 1195 | completion. | |
| 1196 | ||
| 1197 | Note: You can mark several types to match in the AG query. The first AG | |
| 1198 | versions providing this feature allowed only one type, so in this case only the | |
| 1199 | last mark will be used. | |
| 1200 | ||
| 1201 | * Helm git-grep | |
| 1202 | ||
| 1203 | Helm-git-grep searches the current directory, i.e the default directory or the | |
| 1204 | directory in Helm-find-files. If this current directory is a subdirectory of a | |
| 1205 | project and you want to also match parent directories (i.e the whole project), | |
| 1206 | use a prefix argument. | |
| 1207 | ||
| 1208 | ** Commands | |
| 1209 | \\<helm-grep-map> | |
| 1210 | \\[helm-goto-next-file]\t\tNext File. | |
| 1211 | \\[helm-goto-precedent-file]\t\tPrevious File. | |
| 1212 | \\[helm-yank-text-at-point]\t\tYank text at point in minibuffer. | |
| 1213 | \\[helm-grep-run-other-window-action]\t\tJump to other window. | |
| 1214 | \\[helm-grep-run-other-frame-action]\t\tJump to other frame. | |
| 1215 | \\[helm-grep-run-default-action]\t\tRun default action (same as `RET'). | |
| 1216 | \\[helm-grep-run-save-buffer]\t\tSave to a `helm-grep-mode' enabled buffer.") | |
| 1217 | ||
| 1218 | ;;; PDF grep help | |
| 1219 | ;; | |
| 1220 | ;; | |
| 1221 | (defvar helm-pdfgrep-help-message | |
| 1222 | "* Helm PDFgrep Map | |
| 1223 | ||
| 1224 | ** Commands | |
| 1225 | \\<helm-pdfgrep-map> | |
| 1226 | \\[helm-goto-next-file]\t\tNext file. | |
| 1227 | \\[helm-goto-precedent-file]\t\tPrevious file. | |
| 1228 | \\[helm-yank-text-at-point]\t\tYank text at point in minibuffer.") | |
| 1229 | ||
| 1230 | ;;; Etags help | |
| 1231 | ;; | |
| 1232 | ;; | |
| 1233 | (defvar helm-etags-help-message | |
| 1234 | "* Helm Etags Map | |
| 1235 | ||
| 1236 | ** Commands | |
| 1237 | \\<helm-etags-map> | |
| 1238 | \\[helm-goto-next-file]\t\tNext file. | |
| 1239 | \\[helm-goto-precedent-file]\t\tPrevious file. | |
| 1240 | \\[helm-yank-text-at-point]\t\tYank text at point in minibuffer.") | |
| 1241 | ||
| 1242 | ;;; UCS help | |
| 1243 | ;; | |
| 1244 | ;; | |
| 1245 | (defvar helm-ucs-help-message | |
| 1246 | "* Helm UCS | |
| 1247 | ||
| 1248 | ** Tips | |
| 1249 | ||
| 1250 | Use commands below to insert unicode characters in current buffer without | |
| 1251 | leaving Helm. | |
| 1252 | ||
| 1253 | ** Commands | |
| 1254 | \\<helm-ucs-map> | |
| 1255 | \\[helm-ucs-persistent-insert]\t\tInsert character. | |
| 1256 | \\[helm-ucs-persistent-forward]\t\tForward character. | |
| 1257 | \\[helm-ucs-persistent-backward]\t\tBackward character. | |
| 1258 | \\[helm-ucs-persistent-delete]\t\tDelete character backward. | |
| 1259 | \\[helm-ucs-persistent-insert-space]\t\tInsert space.") | |
| 1260 | ||
| 1261 | ;;; Bookmark help | |
| 1262 | ;; | |
| 1263 | ;; | |
| 1264 | (defvar helm-bookmark-help-message | |
| 1265 | "* Helm bookmark name | |
| 1266 | ||
| 1267 | ** Commands | |
| 1268 | \\<helm-bookmark-map> | |
| 1269 | \\[helm-bookmark-run-jump-other-window]\t\tJump other window. | |
| 1270 | \\[helm-bookmark-run-delete]\t\tDelete bookmark. | |
| 1271 | \\[helm-bookmark-run-edit]\t\tEdit bookmark. | |
| 1272 | \\[helm-bookmark-toggle-filename]\t\tToggle bookmark location visibility.") | |
| 1273 | ||
| 1274 | ;;; Eshell command on file help | |
| 1275 | ;; | |
| 1276 | ;; | |
| 1277 | (defvar helm-esh-help-message | |
| 1278 | "* Helm Eshell on file | |
| 1279 | ||
| 1280 | ** Tips | |
| 1281 | ||
| 1282 | *** Pass extra arguments after filename | |
| 1283 | ||
| 1284 | Normally the command or alias will be called with file as argument. For instance | |
| 1285 | ||
| 1286 | <command> candidate_file | |
| 1287 | ||
| 1288 | But you can also pass an argument or more after \"candidate_file\" like this: | |
| 1289 | ||
| 1290 | <command> %s [extra_args] | |
| 1291 | ||
| 1292 | \"candidate_file\" will be added at \"%s\" and the command will look at this: | |
| 1293 | ||
| 1294 | <command> candidate_file [extra_args] | |
| 1295 | ||
| 1296 | *** Specify marked files as arguments | |
| 1297 | ||
| 1298 | Example: | |
| 1299 | ||
| 1300 | <command> file1 file2... | |
| 1301 | ||
| 1302 | Call `helm-find-files-eshell-command-on-file' with one prefix argument. Otherwise | |
| 1303 | you can pass one prefix argument from the command selection buffer. | |
| 1304 | ||
| 1305 | Note: This does not work on remote files. | |
| 1306 | ||
| 1307 | With two prefix-args the output is printed to the `current-buffer'. | |
| 1308 | ||
| 1309 | With no prefix argument or a prefix argument value of '(16) (`\\[universal-argument] \\[universal-argument]') | |
| 1310 | the command is called once for each file like this: | |
| 1311 | ||
| 1312 | <command> file1 | |
| 1313 | <command> file2 | |
| 1314 | ... | |
| 1315 | ||
| 1316 | ** Commands | |
| 1317 | \\<helm-esh-on-file-map>") | |
| 1318 | ||
| 1319 | ;;; Ido virtual buffer help | |
| 1320 | ;; | |
| 1321 | ;; | |
| 1322 | (defvar helm-buffers-ido-virtual-help-message | |
| 1323 | "* Helm Ido virtual buffers | |
| 1324 | ||
| 1325 | ** Commands | |
| 1326 | \\<helm-buffers-ido-virtual-map> | |
| 1327 | \\[helm-ff-run-switch-other-window]\t\tSwitch to other window. | |
| 1328 | \\[helm-ff-run-switch-other-frame]\t\tSwitch to other frame. | |
| 1329 | \\[helm-ff-run-grep]\t\tGrep file. | |
| 1330 | \\[helm-ff-run-zgrep]\t\tZgrep file. | |
| 1331 | \\[helm-ff-run-delete-file]\t\tDelete file. | |
| 1332 | \\[helm-ff-run-open-file-externally]\t\tOpen file externally.") | |
| 1333 | ||
| 1334 | ;;; Moccur help | |
| 1335 | ;; | |
| 1336 | ;; | |
| 1337 | (defvar helm-moccur-help-message | |
| 1338 | "* Helm Moccur | |
| 1339 | ||
| 1340 | ** Tips | |
| 1341 | ||
| 1342 | *** Matching | |
| 1343 | ||
| 1344 | Multiple regexp matching is allowed, simply enter a space to separate the regexps. | |
| 1345 | ||
| 1346 | Matching empty lines is supported with the regexp \"^$\", you then get the | |
| 1347 | results displayed as the buffer-name and the line number only. You can | |
| 1348 | save and edit these results, i.e. add text to the empty line. | |
| 1349 | ||
| 1350 | *** Automatically match symbol at point | |
| 1351 | ||
| 1352 | Helm can automatically match the symbol at point while keeping the minibuffer | |
| 1353 | empty, ready to be written to. This behaviour is disabled by default. To | |
| 1354 | enable this you need to add `helm-source-occur' and `helm-source-moccur' to | |
| 1355 | `helm-sources-using-default-as-input'. | |
| 1356 | ||
| 1357 | *** Jump to the corresponding line in the searched buffer | |
| 1358 | ||
| 1359 | You can do this with `\\<helm-map>\\[helm-execute-persistent-action]' (persistent-action), to do it repeatedly | |
| 1360 | 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]'. | |
| 1361 | ||
| 1362 | *** Switch to buffer in other window | |
| 1363 | ||
| 1364 | The command \\<helm-moccur-map>\\[helm-moccur-run-goto-line-ow] allow you to switch to buffer | |
| 1365 | in other window horizontally or vertically if a prefix arg is supplied. | |
| 1366 | ||
| 1367 | *** Save the results | |
| 1368 | ||
| 1369 | Similarly to Helm-grep, you can save the results with `\\<helm-map>\\[helm-moccur-run-save-buffer]'. | |
| 1370 | Once in the saved buffer, you can edit it, see [[Edit a saved buffer][below]]. | |
| 1371 | ||
| 1372 | Of course if you don't save the results, you can resume the Helm session with | |
| 1373 | `helm-resume'. | |
| 1374 | ||
| 1375 | *** Refresh the resumed session | |
| 1376 | ||
| 1377 | When the buffer(s) where you ran helm-(m)occur get(s) modified, the Helm buffer | |
| 1378 | will flash red as a warning. You can refresh the buffer by running `\\<helm-map>\\[helm-refresh]'. | |
| 1379 | This can be done automatically by customizing `helm-moccur-auto-update-on-resume'. | |
| 1380 | ||
| 1381 | *** Refresh a saved buffer | |
| 1382 | ||
| 1383 | Type `g' to update the buffer. | |
| 1384 | ||
| 1385 | *** Edit a saved buffer | |
| 1386 | ||
| 1387 | First, install wgrep (https://github.com/mhayashi1120/Emacs-wgrep) and then: | |
| 1388 | ||
| 1389 | 1) `C-c C-p' (`wgrep-change-to-wgrep-mode') to edit the buffer(s). | |
| 1390 | 2) `C-x C-s' to save your changes. | |
| 1391 | ||
| 1392 | Tip: Use the excellent iedit (https://github.com/victorhge/iedit) to modify all | |
| 1393 | occurences at once in the buffer. | |
| 1394 | ||
| 1395 | *** Search in region | |
| 1396 | ||
| 1397 | When searching in current-buffer with `helm-occur', if a region | |
| 1398 | is found helm will search in this region only. If you marked | |
| 1399 | this region with `mark-defun' the symbol that was at point before | |
| 1400 | marking defun will be used when `helm-source-occur' is member of | |
| 1401 | `helm-sources-using-default-as-input'. | |
| 1402 | ||
| 1403 | ** Commands | |
| 1404 | \\<helm-moccur-map> | |
| 1405 | \\[helm-goto-next-file]\t\tNext buffer. | |
| 1406 | \\[helm-goto-precedent-file]\t\tPrevious buffer. | |
| 1407 | \\[helm-yank-text-at-point]\t\tYank text at point in minibuffer. | |
| 1408 | \\[helm-moccur-run-goto-line-ow]\t\tGo to line in other window. | |
| 1409 | \\[helm-moccur-run-goto-line-of]\t\tGo to line in new frame.") | |
| 1410 | ||
| 1411 | ;;; Helm Top | |
| 1412 | ;; | |
| 1413 | ;; | |
| 1414 | (defvar helm-top-help-message | |
| 1415 | "* Helm Top | |
| 1416 | ||
| 1417 | ** Commands | |
| 1418 | \\<helm-top-map> | |
| 1419 | \\[helm-top-run-sort-by-com]\t\tSort by commands. | |
| 1420 | \\[helm-top-run-sort-by-cpu]\t\tSort by CPU usage. | |
| 1421 | \\[helm-top-run-sort-by-user]\t\tSort alphabetically by user. | |
| 1422 | \\[helm-top-run-sort-by-mem]\t\tSort by memory.") | |
| 1423 | ||
| 1424 | ;;; Helm Elisp package | |
| 1425 | ;; | |
| 1426 | ;; | |
| 1427 | (defvar helm-el-package-help-message | |
| 1428 | "* Helm Elisp package | |
| 1429 | ||
| 1430 | ** Tips | |
| 1431 | ||
| 1432 | *** Compile all your packages asynchronously | |
| 1433 | ||
| 1434 | If you use async (if you have installed Helm from MELPA you do), only \"helm\", | |
| 1435 | \"helm-core\", and \"magit\" are compiled asynchronously. If you want all your | |
| 1436 | packages compiled asynchronously, add this to your init file: | |
| 1437 | ||
| 1438 | (setq async-bytecomp-allowed-packages '(all)) | |
| 1439 | ||
| 1440 | *** Upgrade Elisp packages | |
| 1441 | ||
| 1442 | On initialization (when Emacs is fetching packages on remote), if Helm finds | |
| 1443 | packages to upgrade, it will start in the upgradable packages view showing the packages | |
| 1444 | available for upgrade. | |
| 1445 | ||
| 1446 | On subsequent runs, you will have to refresh the list with `C-c \\[universal-argument]'. If Helm | |
| 1447 | finds upgrades you can switch to upgrade view (see below) to see what packages | |
| 1448 | are available for upgrade or simply hit `C-c U' to upgrade them all. | |
| 1449 | ||
| 1450 | To see upgradable packages hit `M-U'. | |
| 1451 | ||
| 1452 | Then you can install all upgradable packages with the \"upgrade all\" action | |
| 1453 | \(`C-c \\[universal-argument]'), or upgrade only specific packages by marking them and running the | |
| 1454 | \"upgrade\" action (visible only when there are upgradable packages). Of course | |
| 1455 | you can upgrade a single package by just running the \"upgrade\" action without | |
| 1456 | marking it (`C-c u' or `RET') . | |
| 1457 | ||
| 1458 | \*Warning:* You are strongly advised to \*restart* Emacs after \*upgrading* packages. | |
| 1459 | ||
| 1460 | *** Meaning of flags prefixing packages | |
| 1461 | ||
| 1462 | \(Emacs ≥25) | |
| 1463 | ||
| 1464 | - The flag \"S\" that prefixes package names means that the packages belong to `package-selected-packages'. | |
| 1465 | ||
| 1466 | - The flag \"U\" that prefix package names mean that this package is no more needed. | |
| 1467 | ||
| 1468 | ** Commands | |
| 1469 | \\<helm-el-package-map> | |
| 1470 | \\[helm-el-package-show-all]\t\tShow all packages. | |
| 1471 | \\[helm-el-package-show-installed]\t\tShow installed packages only. | |
| 1472 | \\[helm-el-package-show-uninstalled]\t\tShow non-installed packages only. | |
| 1473 | \\[helm-el-package-show-upgrade]\t\tShow upgradable packages only. | |
| 1474 | \\[helm-el-package-show-built-in]\t\tShow built-in packages only. | |
| 1475 | \\[helm-el-run-package-install]\t\tInstall package(s). | |
| 1476 | \\[helm-el-run-package-reinstall]\t\tReinstall package(s). | |
| 1477 | \\[helm-el-run-package-uninstall]\t\tUninstall package(s). | |
| 1478 | \\[helm-el-run-package-upgrade]\t\tUpgrade package(s). | |
| 1479 | \\[helm-el-run-package-upgrade-all]\t\tUpgrade all packages. | |
| 1480 | \\[helm-el-run-visit-homepage]\t\tVisit package homepage.") | |
| 1481 | ||
| 1482 | ;;; Helm M-x | |
| 1483 | ;; | |
| 1484 | ;; | |
| 1485 | (defvar helm-M-x-help-message | |
| 1486 | "* Helm M-x | |
| 1487 | ||
| 1488 | ** Tips | |
| 1489 | ||
| 1490 | *** You can get help on any command with persistent action (\\[helm-execute-persistent-action]) | |
| 1491 | ||
| 1492 | *** Prefix arguments | |
| 1493 | ||
| 1494 | You must pass prefix arguments \*after* starting `helm-M-x'. A mode-line | |
| 1495 | counter will display the number of given prefix arguments. | |
| 1496 | ||
| 1497 | If you pass prefix arguments before running `helm-M-x', it will be displayed in the prompt. | |
| 1498 | The first `\\[universal-argument]' after `helm-M-x' clears those prefix arguments.") | |
| 1499 | ||
| 1500 | ;;; Helm imenu | |
| 1501 | ;; | |
| 1502 | ;; | |
| 1503 | (defvar helm-imenu-help-message | |
| 1504 | "* Helm Imenu | |
| 1505 | ||
| 1506 | ** Commands | |
| 1507 | \\<helm-imenu-map> | |
| 1508 | \\[helm-imenu-next-section]\t\tGo to next section. | |
| 1509 | \\[helm-imenu-previous-section]\t\tGo to previous section.") | |
| 1510 | ||
| 1511 | ;;; Helm colors | |
| 1512 | ;; | |
| 1513 | ;; | |
| 1514 | (defvar helm-colors-help-message | |
| 1515 | "* Helm colors | |
| 1516 | ||
| 1517 | ** Commands | |
| 1518 | \\<helm-color-map> | |
| 1519 | \\[helm-color-run-insert-name]\t\tInsert the entry name. | |
| 1520 | \\[helm-color-run-kill-name]\t\tKill the entry name. | |
| 1521 | \\[helm-color-run-insert-rgb]\t\tInsert entry in RGB format. | |
| 1522 | \\[helm-color-run-kill-rgb]\t\tKill entry in RGB format.") | |
| 1523 | ||
| 1524 | ;;; Helm Semantic | |
| 1525 | ;; | |
| 1526 | ;; | |
| 1527 | (defvar helm-semantic-help-message | |
| 1528 | "* Helm Semantic | |
| 1529 | ||
| 1530 | ** Commands | |
| 1531 | \\<helm-semantic-map>") | |
| 1532 | ||
| 1533 | ;;; Helm kmacro | |
| 1534 | ;; | |
| 1535 | ;; | |
| 1536 | (defvar helm-kmacro-help-message | |
| 1537 | "* Helm kmacro | |
| 1538 | ||
| 1539 | ** Tips | |
| 1540 | ||
| 1541 | - Start recording a kmacro with `f3'. | |
| 1542 | - End the kmacro recording with `f4'. | |
| 1543 | - Run `helm-execute-kmacro' to list all your kmacros. | |
| 1544 | ||
| 1545 | Use persistent action to run your kmacro as many time as needed. | |
| 1546 | You can browse the kmacros with `helm-next-line' and `helm-previous-line'. | |
| 1547 | ||
| 1548 | Note: You can't record keys running Helm commands except `helm-M-x', under the | |
| 1549 | condition that you don't choose a command using Helm completion. | |
| 1550 | ||
| 1551 | ** Commands | |
| 1552 | \\<helm-kmacro-map>") | |
| 1553 | ||
| 1554 | ;;; Kill ring | |
| 1555 | ;; | |
| 1556 | ;; | |
| 1557 | (defvar helm-kill-ring-help-message | |
| 1558 | "* Helm kill ring | |
| 1559 | ||
| 1560 | ** Tips | |
| 1561 | ||
| 1562 | Every Helm session lets you save a candidate to the kill-ring / clipboard / | |
| 1563 | primary-selection with `\\<helm-map>\\[helm-kill-selection-and-quit]'. | |
| 1564 | ||
| 1565 | To save space, Helm-kill-ring truncates the candidates longer than | |
| 1566 | `helm-kill-ring-max-offset'. | |
| 1567 | `\\<helm-kill-ring-map>\\[helm-kill-ring-kill-selection]' then saves the whole | |
| 1568 | text and not the truncated value. The view of truncated candidates can be | |
| 1569 | toggled; see the command list below. | |
| 1570 | ||
| 1571 | As opposed to `yank', numeric prefix arguments are ignored with | |
| 1572 | `helm-show-kill-ring': there is no need for them since selection happens within | |
| 1573 | Helm. Moreover Helm has [[Shortcuts for executing Default Action on the nth | |
| 1574 | candidate][Shortcuts for executing Default Action on the nth candidate]]. | |
| 1575 | ||
| 1576 | It is recommended to globally bind `M-y' to `helm-show-kill-ring'. Once in the | |
| 1577 | Helm-kill-ring session you can navigate to next/previous line with `M-y' and | |
| 1578 | `M-u' for convenience. Of course `\\[helm-next-line]' and `\\[helm-previous-line]' are still available. | |
| 1579 | ||
| 1580 | It is possible to delete candidates from the kill ring. | |
| 1581 | ||
| 1582 | You can concatenate marked candidates and yank them in the current | |
| 1583 | buffer, thus creating a new entry in the kill ring. Candidates are | |
| 1584 | concatenated with `helm-kill-ring-separator' as default but you can | |
| 1585 | change interactively the separator while yanking by using two prefix | |
| 1586 | args. When you have something else than \"\\n\" as default value for | |
| 1587 | `helm-kill-ring-separator' and you want to use \"\\n\" from prompt, use | |
| 1588 | `C-q C-j' to enter a newline in prompt. | |
| 1589 | ||
| 1590 | To not push a new entry in the kill ring, use `\\<helm-map>\\[helm-copy-to-buffer]' instead of RET | |
| 1591 | \(note that you can't change separator with this). | |
| 1592 | ||
| 1593 | When inserting candidates with the default action (`RET'), `point' is placed at | |
| 1594 | the end of the candidate and `mark' at the beginning. You can revert this behavior | |
| 1595 | by using a prefix argument, i.e. `C-u RET', like the regular `yank' command does. | |
| 1596 | ||
| 1597 | ** Commands | |
| 1598 | \\<helm-kill-ring-map> | |
| 1599 | \\[helm-next-line]\t\tNext line. | |
| 1600 | \\[helm-previous-line]\t\tPrevious line. | |
| 1601 | \\[helm-kill-ring-delete]\t\tDelete entry. | |
| 1602 | \\[helm-kill-ring-toggle-truncated]\t\tToggle truncated view of candidate. | |
| 1603 | \\[helm-kill-ring-kill-selection]\t\tKill non-truncated of selection.") | |
| 1604 | ||
| 1605 | ;;; Org headings | |
| 1606 | ;; | |
| 1607 | ;; | |
| 1608 | (defvar helm-org-headings-help-message | |
| 1609 | "* Helm Org headings | |
| 1610 | ||
| 1611 | ** Tips | |
| 1612 | ||
| 1613 | *** Refiling | |
| 1614 | ||
| 1615 | You can refile one or more headings at a time. | |
| 1616 | ||
| 1617 | To refile one heading, move the point to the entry you want to refile and run | |
| 1618 | \\[helm-org-in-buffer-headings]. Then select the heading you want to refile to | |
| 1619 | and press \\<helm-org-headings-map>\\[helm-org-run-refile-heading-to] or select the refile action from the actions menu. | |
| 1620 | ||
| 1621 | To refile multiple headings, run \\[helm-org-in-buffer-headings] and mark the | |
| 1622 | headings you want to refile. Then select the heading you want to refile to | |
| 1623 | \(without marking it) and press \\<helm-org-headings-map>\\[helm-org-run-refile-heading-to] or select the refile action from the | |
| 1624 | actions menu. | |
| 1625 | ||
| 1626 | *** Tags completion | |
| 1627 | ||
| 1628 | Tags completion use `completing-read-multiple', perhaps have a | |
| 1629 | look at its docstring. | |
| 1630 | ||
| 1631 | **** Single tag | |
| 1632 | ||
| 1633 | From an org heading hit C-c C-c which provide a | |
| 1634 | \"Tags\" prompt, then hit TAB and RET if you want to enter an | |
| 1635 | existing tag or write a new tag in prompt. At this point you end | |
| 1636 | up with an entry in your prompt, if you enter RET, the entry is | |
| 1637 | added as tag in your org header. | |
| 1638 | ||
| 1639 | **** Multiple tags | |
| 1640 | ||
| 1641 | If you want to add more tag to your org header, add a separator[1] after | |
| 1642 | your tag and write a new tag or hit TAB to find another existing | |
| 1643 | tag, and so on until you have all the tags you want | |
| 1644 | e.g \"foo,bar,baz\" then press RET to finally add the tags to your | |
| 1645 | org header. | |
| 1646 | Note: [1] A separator can be a comma, a colon i.e. [,:] or a space. | |
| 1647 | ||
| 1648 | ** Commands | |
| 1649 | \\<helm-org-headings-map> | |
| 1650 | \\[helm-org-run-open-heading-in-indirect-buffer]\t\tOpen heading in indirect buffer. | |
| 1651 | \\[helm-org-run-refile-heading-to]\t\tRefile current or marked headings to selection. | |
| 1652 | \\[helm-org-run-insert-link-to-heading-at-marker]\t\tInsert link at point to selection." | |
| 1653 | ) | |
| 1654 | ||
| 1655 | ;;; Completing-read | |
| 1656 | ;; | |
| 1657 | (defun helm-comp-read-help-message () | |
| 1658 | (let ((com (assoc-default 'name (helm-get-current-source)))) | |
| 1659 | (format | |
| 1660 | "* Helm completing-read completion for `%s' | |
| 1661 | ||
| 1662 | Command `%s' is using a `completing-read' for completion on your input, | |
| 1663 | this completion have been \"helmized\" because you have enabled [[Helm mode][helm-mode]]'. | |
| 1664 | ||
| 1665 | ** Tips | |
| 1666 | ||
| 1667 | *** Disabling or use something else than helm for completion of some commands | |
| 1668 | ||
| 1669 | You can disable helm completion or use something else for specific commands of your choice, | |
| 1670 | for this customize variable `helm-completing-read-handlers-alist'. | |
| 1671 | ||
| 1672 | *** Exiting minibuffer with empty string | |
| 1673 | ||
| 1674 | You can exit minibuffer with empty string with \\<helm-comp-read-map>\\[helm-cr-empty-string]. | |
| 1675 | It is useful when some commands are prompting continuously until you enter an empty prompt. | |
| 1676 | ||
| 1677 | ** Commands | |
| 1678 | \\<helm-comp-read-map> | |
| 1679 | \\[helm-cr-empty-string]\t\tExit minibuffer with empty string." | |
| 1680 | com com))) | |
| 1681 | ||
| 1682 | ||
| 1683 | ;;; Mode line strings | |
| 1684 | ;; | |
| 1685 | ;; | |
| 1686 | ;;;###autoload | |
| 1687 | (defvar helm-comp-read-mode-line "\ | |
| 1688 | \\<helm-comp-read-map>\ | |
| 1689 | C/\\[helm-cr-empty-string]:Empty \ | |
| 1690 | \\<helm-map>\ | |
| 1691 | \\[helm-help]:Help \ | |
| 1692 | \\[helm-select-action]:Act \ | |
| 1693 | \\[helm-maybe-exit-minibuffer]/\ | |
| 1694 | f1/f2/f-n:NthAct \ | |
| 1695 | \\[helm-toggle-suspend-update]:Tog.suspend") | |
| 1696 | ||
| 1697 | ;;;###autoload | |
| 1698 | (defvar helm-read-file-name-mode-line-string "\ | |
| 1699 | \\<helm-read-file-map>\ | |
| 1700 | \\[helm-help]:Help \ | |
| 1701 | C/\\[helm-cr-empty-string]:Empty \ | |
| 1702 | \\<helm-map>\ | |
| 1703 | \\[helm-select-action]:Act \ | |
| 1704 | \\[helm-maybe-exit-minibuffer]/\ | |
| 1705 | f1/f2/f-n:NthAct \ | |
| 1706 | \\[helm-toggle-suspend-update]:Tog.suspend" | |
| 1707 | "String displayed in mode-line in `helm-source-find-files'.") | |
| 1708 | ||
| 1709 | ;;;###autoload | |
| 1710 | (defvar helm-top-mode-line "\ | |
| 1711 | \\<helm-top-map>\ | |
| 1712 | \\[helm-help]:Help \ | |
| 1713 | \\<helm-map>\ | |
| 1714 | \\[helm-select-action]:Act \ | |
| 1715 | \\[helm-maybe-exit-minibuffer]/\ | |
| 1716 | f1/f2/f-n:NthAct \ | |
| 1717 | \\[helm-toggle-suspend-update]:Tog.suspend") | |
| 1718 | ||
| 1719 | ||
| 1720 | (provide 'helm-help) | |
| 1721 | ||
| 1722 | ;; Local Variables: | |
| 1723 | ;; byte-compile-warnings: (not obsolete) | |
| 1724 | ;; coding: utf-8 | |
| 1725 | ;; indent-tabs-mode: nil | |
| 1726 | ;; End: | |
| 1727 | ||
| 1728 | ;;; helm-help.el ends here | |
