Awesome
helm-ag.el
Introduction
helm-ag.el
provides interfaces of The Silver Searcher with helm.
Features
- Support multiple search tools(ag, the platinum searcher, ack etc)
- Edit search result like wgrep
Screenshot
Requirements
- Emacs 27 or higher
- helm 1.7.7 or higher
- The Silver Searcher 0.29.0 or higher.
Installation
helm-ag
is available on MELPA and MELPA stable
You can install helm-ag
with the following command.
<kbd>M-x package-install [RET] helm-ag [RET]</kbd>
Basic Usage
helm-ag
Input search word with ag
command. You can change search directory
with C-u
prefix.
helm-ag-this-file
Same as helm-ag
except to search only current file
helm-do-ag
Search with ag
like helm-do-grep-ag
, helm-grep-do-git-grep
.
You can specify extra command line option of ag
with minus prefix(M--
or C--
).
helm-do-ag-this-file
Same as helm-do-ag
except to search only current file
helm-do-ag-this-file-or-occur
Smartly switch between helm-do-ag-this-file
and helm-occur
based on helm-ag-large-file-threshold
.
helm-ag-project-root
Call helm-ag
at project root. helm-ag
seems directory as project root where
there is .git
or .hg
or .svn
.
helm-do-ag-project-root
Call helm-do-ag
at project root.
helm-ag-buffers
Search buffers by helm-ag
helm-do-ag-buffers
Search buffers by helm-do-ag
helm-ag-pop-stack
Move to point before jump
helm-ag-clear-stack
Clear context stack
Enable helm-follow-mode by default
Please set helm-follow-mode-persistent
to non-nil if you want to use helm-follow-mode
by default. You must set it before loading helm-ag.el
.
(custom-set-variables
'(helm-follow-mode-persistent t))
Persistent action
You can see file content temporarily by persistent action(C-j
).
Search Tips of helm-ag
Passing command line options and pattern
Pattern: -Gmd$ search_pattern
Command line options is -Gmd$
and search pattern is search_pattern
.
helm-ag
treats words which starts with -
as command line option.
Pattern contains space(helm-do-ag
)
Pattern: foo\ bar\ baz
Search pattern is foo\ bar\ baz
. You need to escape spaces with backslash.
In helm-ag
, you need not to escape spaces.
Pattern starts with -
Pattern: -- --count
Search pattern is --count
.
helm-ag
treats words after --
as search pattern.
Search meta characters as literal
ag
(ack
, pt
) takes Perl compatible PCRE so that you need to escape meta characters
likes brackets, braces, asterisk, when you search them as literals.
Use short option
Don't use space between option and its value. For example -tcpp
is ok, -t cpp
is not ok.
Use long option
Please always use =
separator for using long option. Don't use space as separator. For example --ignore=pattern
is ok, --ignore pattern
is not ok.
Customize
helm-ag-base-command
(Default: ag --nocolor --nogroup
)
Base command of ag
. Windows users should set --vimgrep
option for using helm-do-ag
. See #293
helm-ag-command-option
(Default: nil
)
Command line option of base command.
helm-ag-insert-at-point
(Default: nil
)
Insert thing at point as default search pattern, if this value is non nil
.
You can set the parameter same as thing-at-point
(Such as 'word
, symbol
etc).
helm-ag-fuzzy-match
(Default: nil
)
Enable fuzzy matching.
helm-ag-use-grep-ignore-list
(Default: nil
)
Use grep-find-ignored-files
and grep-find-ignored-directories
as ignore pattern.
They are specified to `--ignore' options."
helm-ag-always-set-extra-option
(Default: nil
)
Always set extra command line option of ag
in helm-do-ag
if this value is non-nil.
helm-ag-edit-save
(Default: t
)
Save buffers you edit at editing completed.
helm-ag-use-emacs-lisp-regexp
(Default: nil
)
Use Emacs Lisp regexp instead of PCRE as pattern. NOTE: this is very simple conversion.
helm-ag-use-agignore
(Default: nil
)
Use .agignore
file at project root if this variable is non nil.
helm-ag-use-temp-buffer
(Default: nil
)
Use temporary buffer and not open file for persistent action.
helm-ag-ignore-buffer-patterns
(Default: nil
)
Ignore buffer patterns of buffer search commands.
NOTE
helm
removes file-line
type feature from 1.6.9. So helm-ag-source-type
is no longer available.
Keymap
helm-ag-map
and helm-do-ag-map
are inherited by helm-map
.
Key | Action |
---|---|
C-c o | Open other window |
C-l | Search in parent directory |
C-c C-e | Switch to edit mode |
C-x C-s | Save ag results to buffer(Ask save buffer name if prefix key is specified) |
C-c C-f | Enable helm-follow-mode |
C-c > , right | Move to next file |
C-c < , left | Move to previous file |
C-c ? | Show help message |
Edit mode keymap
Key | Action |
---|---|
C-c C-c | Commit changes |
C-c C-k | Abort |
C-c C-d | Mark delete line |
C-c C-u | Unmark |
You can use next-error
and previous-error
for seeing file content which
current line indicates.
Saved buffer keymap
Key | Action |
---|---|
RET | Jump to current line position |
C-o | Jump to current line position in other window |
g | Update result |
Sample Configuration
(custom-set-variables
'(helm-ag-base-command "ag --nocolor --nogroup --ignore-case")
'(helm-ag-command-option "--all-text")
'(helm-ag-insert-at-point 'symbol)
'(helm-ag-ignore-buffer-patterns '("\\.txt\\'" "\\.mkd\\'")))
helm-ag.el with other searching tools
helm-ag.el
can work other searching tools like platinum searcher or ack instead of the silver searcher.
I think the searching tool which supports grep like output, helm-ag can work with it.
the platinum searcher
(custom-set-variables
'(helm-ag-base-command "pt -e --nocolor --nogroup"))
ack
(custom-set-variables
'(helm-ag-base-command "ack --nocolor --nogroup"))
sift
(custom-set-variables
'(helm-ag-base-command "sift --no-color -n"))
ripgrep
Ripgrep uses exit-status 2 to indicate a partial success:
(custom-set-variables
'(helm-ag-base-command "rg --no-heading --line-number --color never")
`(helm-ag-success-exit-status '(0 2)))
NOTE: For pt and rg users
When using ag
or ack
, helm-do-ag
convert pattern from foo bar
to "(?=.*" foo ".*)(?=.*" bar ".*)"
which pattern matches line which contains both foo
and bar
. But when using pt
or rg
, helm-do-ag
does not convert the pattern because Golang regexp
(pt
is written in Golang)
and rust's regex
(rg
is written in rust) does not support look-a-head pattern.
So using pt
or rg
behaves differently from ag
when you use such pattern.
Alternatives
ag.el provides M-x grep
interface.
Also it can work without helm.