Gtags Hopper

Gtags Hopper is a VS Code extension that enables quick navigation to code definitions and references using GNU GLOBAL (gtags).
Files open in the right editor column for easy side-by-side code comparison.

Requirement: GNU Global 6.5 or later is recommended. Search results are parsed using the --encode-path option to correctly handle file paths that contain spaces; older versions without this option may not parse paths with spaces correctly.

---

Key Features

Code Search & Navigation

• Jump to Definition
  • Definition search using gtags
  • Falls back to GSYMS (symbols with no formal definition, e.g. local variables) if not found in GTAGS, then to local text search (function scope → entire file) as a last resort
  • Optionally searches an external library directory (via gtags-hopper.gtagsLibPath) if the symbol isn't found in the current project
• Jump Back: Return to previous location
• Jump to References: Find all references
• List Symbols in File: Display all symbols in current file
• Search by Grep: Search using regular expressions
• Update Tags: Regenerate gtags database
• Rebuild Tags: Force full regeneration of gtags database (ignores incremental update setting)

Jump History Panel

• Visual History Management: Display jump history in sidebar
• History Navigation: Navigate through history using ▲/▼ buttons
• Position Indicator: Shows your current position in history (e.g. 3 / 12), scoped to filtered results when a search is active
• History Search: Filter history by file name or symbol name
• One-Click Jump: Click history items to jump to any location
• Theme Customization: Choose from 5 themes (shared with the Definition Results panel below)
  • Auto (follows VS Code's current color theme, default)
  • Modern Dark (VSCode style)
  • Modern Light
  • Colorful Dark (gradient style)
  • Colorful Light

Definition Results Panel

• Shown in the bottom panel area (next to Terminal, etc.) when gtags-hopper.resultDisplayMode is panel (default)
• Lists results for Jump to Definition, Jump to References, List Symbols in File, and Search by Grep
• Hover/focus an item to preview it in the editor (can be disabled via gtags-hopper.showPreview)
• Double-click or press Enter to jump; Escape or Ctrl+Alt+[ to cancel
• Shares the same theme setting (gtags-hopper.historyPanelTheme) as the Jump History Panel

Status Bar

• Shows GTAGS status at a glance: a checkmark icon means GTAGS is present, a warning icon means it's missing, and a spinner means tags are currently updating
• Hover for details (last updated time), click to run Update Tags

---

Installation

Visual Studio Code Marketplace

https://github.com/uta1214/gtags-hopper

Manual Installation

1. Clone or download this repository
2. Run npm install to install dependencies
3. Run npm run compile to compile
4. Run vsce package to create .vsix file
5. In VS Code, select "Extensions" → "..." → "Install from VSIX"

---

Usage

Basic Usage

1. Run gtags in your project root to create tags
2. Use keybindings or command palette to invoke features

Keybindings

Default keybindings: | Feature | Key | |---------|-----| | Jump to Definition | Ctrl+Alt+] | | Jump Back | Ctrl+Alt+[ | | Jump to References | Ctrl+Alt+R | | List Symbols | Ctrl+Alt+S | | Update Tags | Ctrl+Alt+T | | Search by Grep | Ctrl+Alt+G |

Rebuild Tags (full regeneration) is available from the Command Palette only (Ctrl+Shift+P → Gtags Hopper: Rebuild Tags).

While multiple results are shown (results panel or QuickPick), pressing Ctrl+Alt+[ (Jump Back) cancels the selection, same as Escape. This does not apply when gtags-hopper.showPreview is false and resultDisplayMode is quickPick (only Escape cancels in that combination).

How to Use History Panel

1. Click Gtags Hopper icon in sidebar
2. "Jump History" panel will appear
3. ▼ Button: Navigate to older history
4. ▲ Button: Navigate to newer history
5. Clear Button: Clear all history
6. Search Box: Filter history by file name or symbol name
7. Click history items to jump directly

---

Configuration

Main Settings

Display Settings

• gtags-hopper.viewColumn: Editor column to open files
  • Choose from first, second, third, active, beside
  • Default: second
• gtags-hopper.usePreviewTab: Open files in preview tab
  • Default: false

Search Behavior

• gtags-hopper.multipleResultAction: Action when multiple results found. Applies to Jump to Definition and Jump to References (not List Symbols / Search by Grep)
  • show: Show results in panel or dialog (depending on resultDisplayMode)
  • firstMatch: Jump to first result automatically
  • Default: show

History Settings

• gtags-hopper.maxHistory: Maximum number of jump history entries
  • Default: 50
• gtags-hopper.centerCursorAfterJumpBack: Center cursor when jumping back
  • Default: false
• gtags-hopper.historyPanelTheme: Theme shared by the Jump History panel and the Definition Results panel
  • Choose from auto, modern-dark, modern-light, colorful-dark, colorful-light
  • auto automatically follows VS Code's current color theme
  • Default: auto

Auto Update Settings

• gtags-hopper.autoUpdateTagsOnSave: Automatically update tags on file save
  • Default: true
• gtags-hopper.autoUpdateDebounceMs: Delay (ms) after the last save before running the update, to avoid redundant runs when saving multiple files in quick succession
  • Default: 1000

Terminal Settings

• gtags-hopper.updateTagsTerminalNew: Create new terminal for Update Tags and Rebuild Tags
• gtags-hopper.listSymbolsInFileTerminalNew: Create new terminal for List Symbols (applies when resultDisplayMode is quickPick)
• gtags-hopper.searchByGrepTerminalNew: Create new terminal for Search by Grep (applies when resultDisplayMode is quickPick)

Gtags Settings

• gtags-hopper.gtagsBinPath: Path to the directory containing the gtags and global executables (e.g. /usr/local/bin). Both binaries are resolved from this single directory since they are normally installed together. Searches PATH if empty
• gtags-hopper.useLoginShell: Run gtags/global via a login shell (-l) so .bashrc/.zshrc environment variables (e.g. GTAGSROOT) are picked up. Set to false to skip this for faster startup in environments with heavy shell init scripts
  • Default: true
• gtags-hopper.gtagsArgs: Additional arguments for gtags execution
  • Example: --gtagslabel=ctags --verbose
  • The value is split on whitespace and each token is passed as a separate argument for safety. Quoting a value to include a space in a single argument (e.g. --extra-flag="foo bar") is not supported.
• gtags-hopper.gtagsLibPath: Path to an external library directory indexed separately with gtags (e.g. a shared internal library or SDK). When set, Jump to Definition also searches it via global -T (GTAGSLIBPATH)
  • Default: empty (disabled)
• gtags-hopper.incrementalUpdate: Use incremental update when GTAGS already exists
  • true: Run global -u (incremental) if GTAGS exists, otherwise full regeneration
  • false: Always run full regeneration
  • Default: true

Result Display Settings

• gtags-hopper.resultDisplayMode: How to display search results
  • panel: Show results in the bottom panel (recommended)
  • quickPick: Show results in QuickPick dialog; terminal output for grep/symbols
  • Default: panel
• gtags-hopper.showPreview: Show a file preview when hovering over results
  • Applies to both panel and quickPick modes
  • Default: true
• gtags-hopper.symbolsPanelAutoFocus: Auto-focus the results panel when List Symbols is executed (applies when resultDisplayMode is panel)
  • Default: false
• gtags-hopper.grepPanelAutoFocus: Auto-focus the results panel when Search by Grep is executed (applies when resultDisplayMode is panel)
  • Default: false

Other Settings

• gtags-hopper.showSearchTime: Display search time in the status bar for a few seconds (Jump to Definition only)
  • Default: false

---

Troubleshooting

Definition Not Found

1. Verify that gtags has been run in project root
2. Check if tag files (GTAGS, GRTAGS, GPATH) exist
3. Update tags using Gtags Hopper: Update Tags if needed

---

License

This project is licensed under the MIT License. (See LICENSE file) Free to use, modify, and redistribute.

---

Author

uta

---

Repository

https://github.com/uta1214/gtags-hopper

---

日本語版 (Japanese)

Gtags Hopper

Gtags Hopper は、GNU GLOBAL (gtags) を使ってソースコードの定義・参照へ素早くジャンプできる VS Code 拡張機能です。
右側のエディタカラムで開くので、コードの見比べがスムーズにできます。

必要要件: GNU Global 6.5 以降を推奨します。検索結果のパースに --encode-path オプションを使用しており、スペースを含むファイルパスを正しく扱うためです。このオプションに対応していない古いバージョンでは、スペースを含むパスが正しく解釈されない場合があります。

---

主な機能

コード検索・ジャンプ

• 定義ジャンプ (Jump to Definition)
  • gtags による定義検索
  • GTAGSで見つからない場合はGSYMS（ローカル変数等、正式な定義を持たないシンボル）にフォールバックし、それでも見つからない場合は最後の手段としてローカルテキスト検索（関数スコープ→ファイル全体）を行う
  • 現在のプロジェクトで見つからない場合、gtags-hopper.gtagsLibPathを設定していれば外部ライブラリのディレクトリも検索する
• 元の位置に戻る (Jump Back)
• 参照ジャンプ (Jump to References)
• ファイル内シンボル一覧 (List Symbols in File)
• Grep 検索 (Search by Grep)
• タグ更新 (Update Tags)
• タグ完全再生成 (Rebuild Tags)：差分更新設定に関わらず常にフル再生成

ジャンプ履歴パネル

• 視覚的な履歴管理: サイドバーにジャンプ履歴を表示
• 履歴ナビゲーション: ▲/▼ボタンで履歴を前後に移動
• 現在位置インジケータ: 履歴内の現在位置を表示（例: 3 / 12）。検索中は絞り込み結果内での位置になる
• 履歴検索: ファイル名やシンボル名で履歴をフィルタリング
• ワンクリックジャンプ: 履歴項目をクリックして任意の位置に戻る
• テーマカスタマイズ: 5種類のテーマから選択可能（下記の定義検索結果パネルと共通）
  • Auto（VS Codeの現在の配色テーマに自動追従、デフォルト）
  • Modern Dark (VSCode スタイル)
  • Modern Light
  • Colorful Dark (グラデーションスタイル)
  • Colorful Light

定義検索結果パネル

• gtags-hopper.resultDisplayMode が panel（デフォルト）のとき、下部パネルエリア（ターミナル等と同じ場所）に表示される
• 定義ジャンプ・参照ジャンプ・ファイル内シンボル一覧・Grep検索の結果を一覧表示
• 項目にフォーカスするとエディタでプレビュー表示（gtags-hopper.showPreview で無効化可能）
• ダブルクリックまたはEnterでジャンプ、Escape または Ctrl+Alt+[ でキャンセル
• ジャンプ履歴パネルと同じテーマ設定（gtags-hopper.historyPanelTheme）を共有する

ステータスバー

• GTAGSの状態がひと目で分かる: チェックアイコンはGTAGSが存在すること、警告アイコンは存在しないこと、スピナーはタグ更新中であることを示す
• ホバーで詳細（最終更新時刻）を表示、クリックでUpdate Tagsを実行

---

インストール方法

Visual Studio Code Marketplace

https://github.com/uta1214/gtags-hopper

手動インストール

1. このリポジトリをクローンまたはダウンロード
2. npm install で依存関係をインストール
3. npm run compile でコンパイル
4. vsce package で .vsix ファイルを作成
5. VS Code で「拡張機能」→「…」→「VSIX からインストール」を選択

---

使い方

基本的な使い方

1. プロジェクトのルートで gtags を実行してタグを作成
2. キーバインドまたはコマンドパレットから機能を呼び出す

キーバインド

既定のキーバインド: | 機能 | キー | |------|------| | Jump to Definition | Ctrl+Alt+] | | Jump Back | Ctrl+Alt+[ | | Jump to References | Ctrl+Alt+R | | List Symbols | Ctrl+Alt+S | | Update Tags | Ctrl+Alt+T | | Search by Grep | Ctrl+Alt+G |

Rebuild Tags（フル再生成）はコマンドパレットからのみ実行できます（Ctrl+Shift+P → Gtags Hopper: Rebuild Tags）。

複数の検索結果が表示されている間（結果パネル・QuickPickいずれも）、Ctrl+Alt+[（Jump Back）を押すとEscapeと同様に選択をキャンセルします。ただしgtags-hopper.showPreviewがfalseかつresultDisplayModeがquickPickの組み合わせのときだけは対象外です（その場合はEscapeのみキャンセル可能）。

履歴パネルの使い方

1. サイドバーの Gtags Hopper アイコンをクリック
2. 「Jump History」パネルが表示されます
3. ▼ボタン: 古い履歴へ移動
4. ▲ボタン: 新しい履歴へ移動
5. Clear ボタン: 履歴をクリア
6. 検索ボックス: ファイル名やシンボル名で履歴を絞り込み
7. 履歴項目をクリックして直接ジャンプ

---

設定

主な設定項目

表示設定

• gtags-hopper.viewColumn: ファイルを開くエディタカラム
  • first, second, third, active, beside から選択
  • デフォルト: second
• gtags-hopper.usePreviewTab: プレビュータブで開くかどうか
  • デフォルト: false

検索動作

• gtags-hopper.multipleResultAction: 複数結果がある場合の動作。Jump to Definition と Jump to References に適用される（List Symbols・Search by Grepには適用されない）
  • show: 結果をパネルまたはダイアログに表示（resultDisplayMode の設定に従う）
  • firstMatch: 最初の結果に自動ジャンプ
  • デフォルト: show

履歴設定

• gtags-hopper.maxHistory: ジャンプ履歴の最大保持数
  • デフォルト: 50
• gtags-hopper.centerCursorAfterJumpBack: Jump Back 時にカーソルを中央に表示
  • デフォルト: false
• gtags-hopper.historyPanelTheme: ジャンプ履歴パネルと定義検索結果パネルで共有されるテーマ
  • auto, modern-dark, modern-light, colorful-dark, colorful-light から選択
  • auto はVS Codeの現在の配色テーマに自動追従する
  • デフォルト: auto

自動更新設定

• gtags-hopper.autoUpdateTagsOnSave: ファイル保存時にタグを自動更新する
  • デフォルト: true
• gtags-hopper.autoUpdateDebounceMs: 最後の保存から実際に更新を実行するまでの遅延時間（ミリ秒）。複数ファイルを連続保存した場合の無駄な実行を防ぐ
  • デフォルト: 1000

ターミナル設定

• gtags-hopper.updateTagsTerminalNew: Update Tags・Rebuild Tags 用の新規ターミナル作成
• gtags-hopper.listSymbolsInFileTerminalNew: List Symbols 用の新規ターミナル作成（resultDisplayMode が quickPick のときのみ有効）
• gtags-hopper.searchByGrepTerminalNew: Search by Grep 用の新規ターミナル作成（resultDisplayMode が quickPick のときのみ有効）

Gtags 設定

• gtags-hopper.gtagsBinPath: gtags・global 実行ファイルが置かれているディレクトリのパス（例: /usr/local/bin）。両者は通常同じ場所にインストールされるため、1つのディレクトリ設定から両方を解決する。空の場合はPATHから検索
• gtags-hopper.useLoginShell: gtags/global をログインシェル（-l）経由で実行するか。.bashrc/.zshrc の環境変数（GTAGSROOT等）を反映するために使用する。シェル初期化が重い環境では false にすると高速化できる
  • デフォルト: true
• gtags-hopper.gtagsArgs: gtags 実行時の追加引数
  • 例: --gtagslabel=ctags --verbose
  • 値は空白区切りで分割され、トークンごとに個別の引数として渡される（安全性のため）。--extra-flag="foo bar" のように1つの引数にスペースを含めたい場合のクォート指定には対応していない。
• gtags-hopper.gtagsLibPath: 別途gtagsでタグ生成済みの外部ライブラリ・SDK等のパス。設定すると定義ジャンプ時にglobal -T（GTAGSLIBPATH）で当該ディレクトリも検索対象にする
  • デフォルト: 空文字（無効）
• gtags-hopper.incrementalUpdate: GTAGS が既に存在する場合に差分更新を使用する
  • true：GTAGS が存在すれば global -u（差分更新）、なければフル生成
  • false：常にフル再生成
  • デフォルト: true

結果表示設定

• gtags-hopper.resultDisplayMode: 検索結果の表示方法
  • panel：結果を下部パネルに表示（推奨）
  • quickPick：QuickPickダイアログで表示、grep/シンボルはターミナル出力
  • デフォルト: panel
• gtags-hopper.showPreview: 結果にフォーカスを当てたときにファイルプレビューを表示する
  • panel・quickPick 両方に適用される
  • デフォルト: true
• gtags-hopper.symbolsPanelAutoFocus: List Symbols 実行時に結果パネルを自動でフォーカスするか（resultDisplayMode が panel のときのみ有効）
  • デフォルト: false
• gtags-hopper.grepPanelAutoFocus: Search by Grep 実行時に結果パネルを自動でフォーカスするか（resultDisplayMode が panel のときのみ有効）
  • デフォルト: false

その他

• gtags-hopper.showSearchTime: 検索時間を数秒間ステータスバーに表示する（現在はJump to Definitionのみに適用）
  • デフォルト: false

---

トラブルシューティング

定義が見つからない

1. プロジェクトルートで gtags を実行してタグを生成しているか確認
2. タグファイル (GTAGS, GRTAGS, GPATH) が存在するか確認
3. 必要に応じて Gtags Hopper: Update Tags でタグを更新

---

ライセンス

このプロジェクトのライセンスは MIT です。（LICENSE ファイル参照） 自由に利用・改変・再配布が可能です。

---

作者

uta

---

リポジトリ

https://github.com/uta1214/gtags-hopper

---