IDE-like Source Code Searcher on Shell for IntelliJ

Since IntelliJ doesn't allow searching multiple directories (related codebases) simultaneously, I have written a portable script on Bash and Zsh to do the job and unlike other source code searchers on shell, it also provides modern-IDE-like features such as opening the source code file from the search result.

This script currently supports Vim, NeoVim (terminal version) and IntelliJ as the editors for the source code files.

1. If you want to work completely on the shell, then choose Vim / NeoVim
2. If you choose to use IntelliJ, Vim will be used as the pager to show the search result and IntelliJ will be used to open the source code file from the search result.

Table of content

1. Why did I make it?
2. Installation
3. Quick start
4. Configuration
5. Usage details
   1. Shell command
   2. Vim skills for using this script
      1. Basic
      2. Advanced
6. Tested environment

Why did I make it?

The code searching function of IntelliJ (Community Edition) has below limitation.

This was really a pain to me since I quite often needed to search multiple related codebases siumltaneously. Therefore, I explored for the alternatives that may run on my IntelliJ's terminal to do the job. Below are some of my expectations to the source code searchers.

1. Able to search multiple directories.
2. The format of the search result is designed for source code searching, unlike grep.
3. Automatically ignores the build folder, library folder, .git/, .idea/ and etc.
4. IDE-like feature: Do not only show the lines of code that contain the keywords, but there should also be a separate window to show the list of files that contains the keywords.
5. IDE-like feature: May choose to read which file's search result from the above file list.
6. IDE-like feature: May instantly open the source code file from the search result.

Unfortunately, so far what I have found only met the first 3 points. Therefore, I wrote the script.

Installation

1. Copy and paste the script into your bashrc or zshrc file, or
2. In your bashrc or zshrc file, source this script.

Quick start

1. Run below command on your Bash or Zsh
   1. Examples:

      # Search dirA and dirB (in your current directory by default) recursively for patternA or patternB
      gp 'regex-of-dirA-partial-name\|regex-of-dirB-partial-name' regex-of-patternA\\\|regex-of-patternB
      
      # Search the codebases (in your current directory by default) recursively for patternA and at the same time, ignore the *test (in glob pattern) and resources directories, ignore the *.txt (in glob pattern) files
      gp 'regex-of-codebases-dir-partial-name' 'regex-of-patternA' --exclude-dir={\*test,resources} --exclude=\*.txt
      
      # Search all the files and directories (in your current directory by default) recursively for patternA (case-insensitive)
      gp . 'regex-of-patternA' -i

   2. Syntax: gp <parts-of-file-and-directory-names> <pattern> [-i|--ignore-case] [-w|--word-regex] [--include=<files>] [--exclude=<files>] [--exclude-dir=<directories>]
   3. Check this for the details
2. The search result will then be rendered on Vim
   1. Glance at its UI
      1. 
      2. 
   2. Chooes to read which file's preview
      1. 
      2. You may actually directly CLICK on it with your mouse, instead of pressing <Enter>, to open the preview and SCROLL to browse if you Vim supports this!
   3. Open the source code file from the search result
      1. 
      2. IntelliJ or Vim will be used to load the source code file, depending on your configuration
      3. Check the (7) in this to learn more about \gp
   4. Jump to the next / previous occurrence of the keywords (the <pattern> specified in your shell command)
      1. 
      2. Check the (6)(iii) in this to learn more about n
   5. The last searched pattern on Vim are actually highlighted
      1. 
      2. Check the (8) in this to learn how to turn off the highlighting
   6. Check this to learn more about how to use Vim

Configuration

Modify below configuration in the script if you want or need to.

MAPPED_KEY_TO_NAVIGATE_TO_FILES='<Leader>gp' # change this value if it has a conflict with your Vim setting
ENCODING='utf-8' # change this value if the encoding is not UTF-8

## You may temporarily modify below configurable parameters on your shell before executing the search, e.g. `GP_MAXDEPTH=2; gp x x`,
## or permanently by modifying their values in this script
GP_SOURCE_CODE_FILE_EDITOR='vim' # supported values: vim, nvim, intellij
GP_SOURCE_CODE_FILE_EDITOR_LAUNCHER_PATH='' # leave it an empty value if you use Vim / NeoVim
GP_NUM_OF_CTX_LINES=10 # the number of lines to show before and after matches of the keywords
GP_MAXDEPTH=1 # the depth of directories to search for <parts-of-file-and-directory-names>, e.g. 1 value to search only current directory for <parts-of-file-and-directory-names>
GP_EXCLUDE_DIR=('lib' 'libs' 'build' 'bin' '.?*')
GP_EXCLUDE=('png' 'jpeg' 'jpg' 'tif' 'tiff' 'bmp' 'gif' 'eps' 'raw' 'cr2' 'nef' 'orf' 'sr2' 'swo' 'swp' '?*~' 'lib' 'dll' 'a' 'o' 'class' 'jar')
GP_SEARCH_RESULT_FILENAME='GP_SEARCH_RESULT.txt' # the file generated to temporarily store the search result

Configuration for setting IntelliJ the source code file editor:

1. Check this to learn more about how to set SOURCE_CODE_FILE_EDITOR_LAUNCHER_PATH for IntelliJ.
2. If you are a Mac user, you may need to search about how to create the IntelliJ command-line launcher in your environment.
3. Examples
   1. Windows > Git Bash
      1. SOURCE_CODE_FILE_EDITOR_LAUNCHER_PATH='/c/Program\ Files/JetBrains/IntelliJ\ IDEA\ Community\ Edition\ 2021.3.1/bin/idea64.exe'
   2. MacOS > Zsh
      1. SOURCE_CODE_FILE_EDITOR_LAUNCHER_PATH='/Applications/JetBrains\ Toolbox.app/Contents/idea'
      2. Please note that you need to firstly create your command-line launcher

Usage details

Shell command

gp <parts-of-file-and-directory-names> <pattern> [-i|--ignore-case] [-w|--word-regex] [--include=<files>] [--exclude=<files>] [--exclude-dir=<directories>]

1. <parts-of-file-and-directory-names>
   1. A string of regex.
   2. It defines what to search in your current working directory.
2. <pattern>
   1. A string of regex.
   2. It defines the pattern to search for.
3. [-i|--ignore-case]
   1. An option to make the <pattern> search case-insensitive.
4. [-w|--word-regex]
   1. An option to request that the <pattern> has to match the full (not partial) word to produce a match.
5. [--include=<files>] [--exclude=<files>] [--exclude-dir=<directories>]
   1. This script makes use of grep to do the search.
   2. The above options will be passed to grep.
   3. You may check your grep manual to learn more about these options.
   4. Please note that the behaviour of grep in response to these arguments varies with different shells.

Vim skills for using this script

Basic

1. A brief idea about normal mode, command mode and insert mode
2. Cursor movement
   1. One-line movement in normal mode
      1. h for left, j for downward, k for upward, l for right
   2. Page-wise movement in normal mode
      1. <ctrl-d> for half page downward, <ctrl-u> for half page upward
3. Move to another window, e.g. from the file list window to the preview window
   1. <ctrl-w> then h or j or k or l in normal mode to move to the surrounding window
4. Exit Vim
   1. :qa to leave Vim
   2. :qa! to leave Vim forcefully and your unsaved changes will be abandoned
5. Select a file in the file list and show its preview
   1. In the file list, move your cursor to the file and press <Enter>
6. Search through the previews
   1. Go to the preview window
   2. /<regex-pattern> to search forward, ?<regex-pattern> backward
   3. n to repeat the last search, N the last search in a reverse order
   4. Check this for more information
7. Navigate to the souce code files that you want to learn more
   1. Go to the preview window
   2. Go to the line of code you are interested in
   3. Type <Leader>gp in normal mode
      1. <Leader> in Vim by default means \
      2. <Leader>gp means \gp by default
   4. Afterwards, it will bring you to that line of code
   5. If you use Vim as the source code file editor, <ctrl-6> in normal mode to go back to the preview
8. :nohlsearch (or :noh) to turn off the last searched pattern's highlighting

Advanced

1. Jump to the next or previous file's preview when you are in the preview window
   1. { and } in normal mode
2. Jump to the 1st line / the last line
   1. gg to the 1st line and G to the last line
3. Preview the next or previous file in the file list, regardless of where you are on Vim
   1. :cnext (or :cn) to preview the next file, :cprevious (or :cp) the previous file
4. Close and open the file catalouge
   1. :cclose (or :ccl) to close, :copen (or :cope) to open
5. Show multiple file previews at the same time
   1. :vsplit (or :vs) in the preview window to create a vertical split window to view the previews
   2. :split (or :sp) to make a horizontal split window
   3. <ctrl-w>q to close the current window
6. Make your current line at the top / center / bottom of your screen
   1. In normal mode, zt to make your current line at the screen top, zz the center, zb the bottom
7. Bookmark your preview
   1. In normal mode, m to mark and backtick to go back to that marked location
   2. Check this for more information

Tested environment

1. macOS Monterey version 12.0.1
   1. zsh 5.8 (x86_64-apple-darwin21.0)
   2. GNU bash, version 3.2.57(1)-release (arm64-apple-darwin21)
   3. VIM - Vi IMproved 8.2 (2019 Dec 12, compiled Sep 26 2021 21:11:52), macOS version - arm64, Included patches: 1-3458, Compiled by Homebrew
   4. NVIM v0.5.0, Build type: Release, LuaJIT 2.1.0-beta3, Compiled by brew@HMBRW-A-001-M1-005.local
2. Git Bash
   1. GNU bash, version 4.4.23(1)-release (x86_64-pc-msys)
   2. VIM - Vi IMproved 8.2 (2019 Dec 12, compiled Sep 21 2021 16:13:20), Included patches: 1-3441, Compiled by <https://www.msys2.org/>