Skip to main content
Gitlantis represents your project structure as an ocean world where folders and files appear as 3D objects. This guide shows you how to interact with them effectively.

​
Opening Files and Folders

Navigate your project by sailing to files and folders and interacting with them.
1

Approach an Object

Sail your boat toward any file or folder object in the world:
  • Folder objects: Represented by folder 3D models
  • File objects: Represented by file 3D models
  • Collision detection activates when you get close enough
The system tracks which objects you’re currently colliding with. See src/browser/hooks/useNode/shortcuts/index.ts:23-29.
2

Open with Keyboard Shortcut

While colliding with an object, use a keyboard shortcut to open it:
  • Shift + Enter: Open the file or explore the folder
  • The shortcut is throttled to 500ms to prevent accidental double-opens
When you open a folder, the view updates to show that folder’s contents. When you open a file, VS Code opens it in the editor. See src/browser/hooks/useNode/shortcuts/index.ts:75-86 and src/browser/config/index.ts:11-15.
3

File vs Folder Behavior

The system handles files and folders differently:
  • Files (type: "file"): Sends an open_file command to VS Code
  • Folders (type: "folder"): Updates the current path to show folder contents
See src/browser/hooks/useNode/shortcuts/index.ts:34-42 and src/extension/handlers/openFile/index.ts:4-9.
Move through your project’s folder structure efficiently.
1

Enter a Directory

To explore a folder:
  1. Sail your boat to a folder object
  2. Wait until you’re in collision range
  3. Press Shift + Enter
  4. The world updates to show the folder’s contents
The current path updates and breadcrumbs reflect your new location. See src/extension/handlers/readDirectory/index.ts:10-36.
2

Go Back One Directory

Press Escape to navigate up one directory level:
  • Returns you to the parent folder
  • Throttled to 500ms to prevent accidental navigation
  • Won’t go above the base project folder
See src/browser/hooks/useNode/shortcuts/index.ts:49-62 and src/browser/hooks/useNode/shortcuts/index.ts:70-73.
3

Jump to Any Parent Directory

Use breadcrumbs to jump directly to any parent folder:
  • Click on any folder name in the breadcrumb path
  • Instantly navigate to that directory without sailing
  • Useful for moving up several levels at once
See the Navigating the World guide for more on breadcrumbs.

​
Reading Directory Contents

Understand how Gitlantis loads and displays your project structure.
1

Directory Loading Process

When you navigate to a folder, Gitlantis:
  1. Reads the directory using VS Code’s file system API
  2. Identifies the folder URI and label
  3. Retrieves all entries (files and folders)
  4. Categorizes each entry by type
See src/extension/handlers/readDirectory/index.ts:6-16.
2

Understanding File Types

Each entry is categorized as:
  • Folder (type: "folder"): Directories you can explore
  • File (type: "file"): Files you can open
  • Unknown (type: "unknown"): Other file system entries
  • Symlink flag (isSymlink: boolean): Whether the entry is a symbolic link
See src/extension/handlers/readDirectory/index.ts:18-28.
3

Directory Response Structure

When a directory loads successfully, Gitlantis sends:
{
  label: folderLabel,        // Display name
  type: "data",              // Response type
  path: message.path,        // Full path
  children: [...],           // Files and folders
  baseFolder: baseFolder     // Project root
}
See src/extension/handlers/readDirectory/index.ts:30-36.

​
Keyboard Shortcuts Reference

All available keyboard shortcuts for file and folder management.

Shift + Enter

Open file or explore folder (when colliding with object)

Escape

Go back one directory level

H

Sound the boat horn (no file operation)

​
Shortcut Key Detection

Gitlantis uses a key tracking system for reliable shortcut detection:
1

Key Tracking

The system maintains a set of currently pressed keys:
  • Keys are added to the set on keydown events
  • Keys are removed from the set on keyup events
  • The set is cleared when the window loses focus
This allows for accurate detection of key combinations. See src/browser/hooks/useNode/shortcuts/index.ts:21 and src/browser/hooks/useNode/shortcuts/index.ts:91-92.
2

Combination Detection

For shortcuts with multiple keys (like Shift + Enter):
const combinationPressed = shortcut.keys.every((requiredKey) =>
  pressedKeys.current.has(requiredKey)
);
All required keys must be in the pressed set simultaneously. See src/browser/hooks/useNode/shortcuts/index.ts:76-78.
3

Throttling

File/folder operations are throttled to 500ms:
  • Prevents accidental double-opening
  • Uses trailing: false to trigger immediately
  • Independent throttles for “open” and “go back” actions
See src/browser/hooks/useNode/shortcuts/index.ts:31-46 and src/browser/hooks/useNode/shortcuts/index.ts:49-62.

​
File Opening Details

When you open a file:
  1. Your browser sends a message to the VS Code extension
  2. The extension receives the open_file command with the file path
  3. VS Code creates a URI from the file path
  4. VS Code opens the file in a text editor
If the file cannot be opened, an error message appears. See src/extension/handlers/openFile/index.ts:3-10.
If a file can’t be opened:
vscode.window.showErrorMessage(`Cannot open the file at: ${filePath}`);
This typically happens when:
  • The file path is invalid
  • The file has been deleted or moved
  • There are permission issues
See src/extension/handlers/openFile/index.ts:8.
Gitlantis tracks collisions using a ref array:
collisionStateRef: RefObject<boolean[]>
  • Each index corresponds to a node (file/folder)
  • true means the boat is colliding with that node
  • The first colliding node is selected when you press a shortcut
See src/browser/hooks/useNode/shortcuts/index.ts:13 and src/browser/hooks/useNode/shortcuts/index.ts:23-29.

​
Tips for Efficient File Management

  • Use shortcuts: Memorize Shift+Enter and Escape for fast navigation
  • Watch breadcrumbs: Always know where you are in the project structure
  • Sail close: Make sure you’re in collision range before trying shortcuts
  • Use the minimap: Quickly locate folders in large projects
  • Go back with Escape: Faster than sailing back to the parent folder icon

Build docs developers (and LLMs) love

Get started for freeTalk to us