This plugin uses ad-hoc searches to find strings in files. For certain
languages, it can also find variable/function/class definitions,
function calls etc.
Other than |tags| or |cscope|, it doesn't build a database to speed up
searches but always scans all files. It can make use of the following
external tools in order to gain acceptable performance for medium-sized
projects:
- `git grep`
- `ack` http://beyondgrep.com/
- `ag` https://github.com/ggreer/the_silver_searcher
- `sift` https://sift-tool.org/
The builtin vimscript-based version file scanner and also
|vimgrep| are suitable for small projects. See |g:trag#grep_type| for
available options.
Usage~
First, define which files belong to your project. See
|g:trag#file_sources| for available sources. If the variable contains
"vcs" and the current buffer is under control of a supported VCS, trag
will scan the files in the VCS. Maybe your project's source files are
already registered in your tags files, in which case those will be used.
Secondly, use |:Trag| to scan your project's files. You can restrict searches
to certain "kinds" like only variable definitions or only function calls. See
|trag-kinds| for details.
You can also type <Leader>r# to search for the word under cursor (see
|g:trag_map_leader| and |TragInstallMap()| for details on maps). In
supported filetypes, <Leader>rd will search for the definition of the
word under cursor.
Currently the following filetypes are supported:
- java
- javascript
- json
- make
- r
- ruby
- viki
- vim
Run `:echo globpath(&rtp, 'ftplugin/*/trag.vim')` to get a full listing
of supported filetypes.
NOTE: Some kinds are available only for a subset of known filetypes.
Default maps (see also |TragInstallMap()|):
<Leader>rr ... Trag the word under cursor
<Leader>rq ... Show |quickfix|list via |:Tragcw|
<Leader>rl ... Show |location-list| via |:Traglw|
<Leader>rf ... Edit a file from the files list, i.e. the list that would be
used if no "--file_sources" argument were passed to
|:Trag|
<Leader>r<Leader>x ... The same as `:Trag -l -i=x -x=i <cword><cr>`
where x is a alphabetical letter that describes a kind in
|g:trag_kinds| and <cword> is the word under cursor.
"-x=i" (exclude commented text) is only added if kind x is
in |g:trag_kinds_ignored_comments|.
-----------------------------------------------------------------------
Install~
Edit the vba file and type: >
:so %
See :help vimball for details. If you have difficulties or use vim 7.0,
please make sure, you have the current version of vimball (vimscript
#1502) installed.
This script requires tlib (vimscript #1863) to be installed.
-----------------------------------------------------------------------
*trag-kinds*
Kinds~
Certain commands take a "kind" as argument. A "kind" in the context of
trag means a way how the expression is interpreted and (in the future)
how the lines are scanned. The meaning of the letter is specific for a
certain filetype. In general, the following list should serve as a
common base:
c ... class definitions
d ... function/method definitions
f ... function calls
i ... ignored lines, comments etc.
l ... variable definition
m ... module definitions
r ... variable assignment (e.g. "= WORD")
u ... uses of word (ignore comments)
w ... find as word
x ... subclasses
fuzzy ... use a typo-tolerant regexp
todo ... TODO markers etc.
EXPERIMENTAL: Kinds can be joined as comma-separated list (OR) of
period-seprated list (CONTAIN). This may be unintuitive but that's the
way it is. Order in CONTAIN-patterns matters, i.e. w.i doesn't make too
much sense (a word that CONTAINs a comment, which could only be the word
itself) but i.w does (a comment that CONTAINs a word, which is quite
possible).
The available command-line options are documented in |:Trag|. These
command-line options allow users to defined which lines should be matched.
Example:
-i=l,r ...... a word either on the left OR right hand side of an
assignment
-x=i ........ match lines that are not comments
-i=w -x=i ... word that is NOT contained in a comment
More examples:
File contents: >
#1 function Foo() {}
#2 function FooBar() {}
#3 let x = FooBar()
#4 let x = Foo()
<
:TRag Foo
=> Find "Foo": 1-4
:TRag -i=w Foo
=> Find the __w__ords "Foo": 1, 4
:TRag -i=d Foo
=> Find __d__efinitions of "Foo": 1, 2
:TRag -i=d.w Foo
=> Find __d__efinitions of the __w__ord "Foo": 1
:TRag -i=f Foo
=> Find (__f__unction) calls of "Foo": 3, 4
:TRag -i=f.w Foo
=> Find (__f__unction) calls of the __w__ord "Foo": 4
Not every kind is defined for every filetype. Currenty, support for
the following filetype(s) is somewhat above average:
- ruby
- vim
Use |:TRagDefKind| to define new kinds.
See |trag#Grep()| for details of how to use this.
-----------------------------------------------------------------------
Install~
To install the vimball, edit the vba file and type: >
:so %
See :help vimball for details.
To install from github, please use
1. git + a plugin loader like enable_vim, pathogen, vim-unbundle etc.
2. a plugin manager like VAM, Vundle, NeoBundle, vim-plug etc.
The tlib_vim plugin is required:
https://github.com/tomtom/tlib_vim
Also available via git: http://github.com/tomtom/trag_vim
Dependencies:
tlib (>= 1.23) :: http://github.com/tomtom/tlib_vim
License: GPLv3 or later