File Navigation - Magictt Neovim Config

Magictt provides multiple powerful tools for navigating files and projects: Telescope for fuzzy finding, nvim-tree for file exploration, and Harpoon for quick file switching.

Fuzzy Finder: Telescope

Telescope is a highly extendable fuzzy finder for files, text, and more. It’s the primary way to navigate and search in Magictt.

Features

Fast Fuzzy Finding: Quickly find files by typing partial names
Live Grep: Search text across entire project
Smart Path Display: Shows relevant parts of file paths
FZF Integration: Uses native FZF for better performance
TODO Integration: Search for TODO comments
Preview Window: Preview file contents before opening

Keybindings

Keybinding	Action	Description
`<leader>ff`	Find Files	Fuzzy find files in current directory
`<leader>fr`	Recent Files	Find recently opened files
`<leader>fs`	Find String	Live grep - search text in all files
`<leader>fc`	Find Cursor	Find string under cursor in project
`<leader>ft`	Find TODOs	Search TODO comments with Telescope

Once in Telescope:

Keybinding	Action
`<C-j>`	Move to next result
`<C-k>`	Move to previous result
`<C-q>`	Send selected to quickfix list
`<CR>`	Open selected file
`<Esc>`	Close Telescope

Usage Workflows

Find Files

Press <leader>ff
Start typing filename (fuzzy matching)
Navigate results with <C-j>/<C-k>
Press <CR> to open file

<leader>ff
Type: "main.js"
Matches: src/main.js, lib/mainController.js

Search Text

Press <leader>fs
Type search term
Results update live as you type
Preview shows context
Open file with <CR>

<leader>fs
Type: "function handleClick"
Finds all occurrences across project

Find Under Cursor

Place cursor on word
Press <leader>fc
Telescope searches for that word
See all occurrences

Recent Files

Press <leader>fr
See recently opened files
Quick access to your working set

Configuration

Location: lua/magictt/plugins/telescope.lua

return {
  "nvim-telescope/telescope.nvim",
  branch = "0.1.x",
  dependencies = {
    "nvim-lua/plenary.nvim",
    { "nvim-telescope/telescope-fzf-native.nvim", build = "make" },
    "nvim-tree/nvim-web-devicons",
    "folke/todo-comments.nvim",
  },
  config = function()
    local telescope = require("telescope")
    local actions = require("telescope.actions")

    telescope.setup({
      defaults = {
        path_display = { "smart" },  -- Smart path truncation
        mappings = {
          i = {
            ["<C-k>"] = actions.move_selection_previous,
            ["<C-j>"] = actions.move_selection_next,
            ["<C-q>"] = actions.send_selected_to_qflist + actions.open_qflist,
          },
        },
      },
    })

    -- Load FZF extension for better performance
    telescope.load_extension("fzf")

    -- Keybindings
    local keymap = vim.keymap
    keymap.set("n", "<leader>ff", "<cmd>Telescope find_files<cr>")
    keymap.set("n", "<leader>fr", "<cmd>Telescope oldfiles<cr>")
    keymap.set("n", "<leader>fs", "<cmd>Telescope live_grep<cr>")
    keymap.set("n", "<leader>fc", "<cmd>Telescope grep_string<cr>")
    keymap.set("n", "<leader>ft", "<cmd>TodoTelescope<cr>")
  end,
}

FZF Native Extension

The telescope-fzf-native extension provides:

Faster sorting
Better fuzzy matching algorithm
Native C implementation for performance

Requires make to build during installation.

File Explorer: nvim-tree

nvim-tree is a file explorer tree that provides a traditional sidebar view of your project structure.

Features

Tree View: Hierarchical file/folder display
Git Integration: Shows git status for files
Icons: File type icons and folder indicators
Relative Numbers: Line numbers for quick navigation
Indent Markers: Visual guides for tree structure
File Operations: Create, rename, delete files/folders

Keybindings

Open/Close

Keybinding	Action
`<leader>ee`	Toggle file explorer
`<leader>ef`	Toggle explorer on current file
`<leader>ec`	Collapse file explorer
`<leader>er`	Refresh file explorer

Inside nvim-tree

Keybinding	Action
`<CR>`	Open file/folder
`o`	Open file/folder
`<C-v>`	Open in vertical split
`<C-x>`	Open in horizontal split
`<C-t>`	Open in new tab
`<BS>`	Close directory
`P`	Go to parent directory
`K`	Go to first sibling
`J`	Go to last sibling
`r`	Rename file/folder
`a`	Create new file/folder
`d`	Delete file/folder
`c`	Copy file/folder
`x`	Cut file/folder
`p`	Paste file/folder
`y`	Copy filename
`Y`	Copy relative path
`gy`	Copy absolute path
`g?`	Show help
`q`	Close tree

Git Status Icons

✓ Staged
✗ Deleted
★ Renamed
✚ Untracked
● Modified
◌ Ignored

File Operations Workflow

Create File/Folder

Open nvim-tree (<leader>ee)
Navigate to desired location
Press a (add)
Type name (add / at end for folder)
Press <CR>

Rename File

Navigate to file
Press r
Edit name
Press <CR>
LSP automatically updates imports (via nvim-lsp-file-operations)

Delete File

Navigate to file
Press d
Confirm deletion

Configuration

Location: lua/magictt/plugins/nvim-tree.lua

return {
  "nvim-tree/nvim-tree.lua",
  dependencies = "nvim-tree/nvim-web-devicons",
  config = function()
    local nvimtree = require("nvim-tree")

    -- Disable netrw (Vim's default file explorer)
    vim.g.loaded_netrw = 1
    vim.g.loaded_netrwPlugin = 1

    nvimtree.setup({
      view = {
        width = 35,              -- Tree width in columns
        relativenumber = true,   -- Show relative line numbers
      },
      renderer = {
        indent_markers = {
          enable = true,         -- Show indent guide lines
        },
        icons = {
          glyphs = {
            folder = {
              arrow_closed = "",  -- Closed folder arrow
              arrow_open = "",    -- Open folder arrow
            },
          },
        },
      },
      actions = {
        open_file = {
          window_picker = {
            enable = false,      -- Better split behavior
          },
        },
      },
      filters = {
        custom = { ".DS_Store" }, -- Hide macOS files
      },
      git = {
        ignore = false,          -- Show .gitignored files
      },
    })

    -- Keybindings
    local keymap = vim.keymap
    keymap.set("n", "<leader>ee", "<cmd>NvimTreeToggle<CR>")
    keymap.set("n", "<leader>ef", "<cmd>NvimTreeFindFileToggle<CR>")
    keymap.set("n", "<leader>ec", "<cmd>NvimTreeCollapse<CR>")
    keymap.set("n", "<leader>er", "<cmd>NvimTreeRefresh<CR>")
  end,
}

Harpoon provides lightning-fast navigation between your most important files in a project.

Concept

Harpoon lets you “mark” files and quickly jump between them:

Add files to your Harpoon list
Navigate with simple keybindings
Perfect for files you’re actively working on

Features

Quick Marks: Mark important files
Fast Navigation: Jump between marked files instantly
Visual Menu: See all marked files
Persistent: Marks persist per project
Minimal: No visual clutter

Keybindings

Keybinding	Action
`<leader>ha`	Add current file to Harpoon
`<leader>hr`	Remove current file from Harpoon
`<C-e>`	Toggle Harpoon quick menu
`<C-p>`	Navigate to previous Harpoon file
`<C-n>`	Navigate to next Harpoon file

Workflow

Typical Harpoon Session

Mark Files

Open src/main.js
Press <leader>ha (file added to Harpoon)

Open src/utils.js
Press <leader>ha (file added to Harpoon)

Open src/api.js
Press <leader>ha (file added to Harpoon)

Navigate Between Files

Press <C-n> (jump to utils.js)
Press <C-n> (jump to api.js)
Press <C-p> (jump back to utils.js)

View All Marks

Press <C-e> (opens menu)
See all marked files
Navigate and select

Remove Marks

Open file to remove
Press <leader>hr (removed from Harpoon)

Use Cases

Active Development: Mark the 3-4 files you’re currently working on
Code Review: Mark files under review for easy switching
Related Files: Mark implementation, test, and config files
Quick Context Switch: Jump between feature files

Configuration

Location: lua/magictt/plugins/harpoon.lua

return {
  "ThePrimeagen/harpoon",
  branch = "harpoon2",
  dependencies = { "nvim-lua/plenary.nvim" },
  config = function()
    local harpoon = require("harpoon")
    harpoon:setup()
    
    -- Register with which-key
    require("which-key").add({
      { "<leader>h", group = "Harpoon" },
    })

    -- Add file to Harpoon
    vim.keymap.set("n", "<leader>ha", function()
      harpoon:list():add()
    end, { desc = "Harpoon: Add file" })

    -- Toggle quick menu
    vim.keymap.set("n", "<C-e>", function()
      harpoon.ui:toggle_quick_menu(harpoon:list())
    end, { desc = "Harpoon: Toggle menu" })

    -- Navigate to previous file
    vim.keymap.set("n", "<C-p>", function()
      harpoon:list():prev()
    end, { desc = "Harpoon: Previous file" })

    -- Navigate to next file
    vim.keymap.set("n", "<C-n>", function()
      harpoon:list():next()
    end, { desc = "Harpoon: Next file" })

    -- Remove current file
    vim.keymap.set("n", "<leader>hr", function()
      harpoon:list():remove()
    end, { desc = "Harpoon: Remove current file" })
  end,
}

When to Use Each Tool

Tool	Best For	Speed	Use Case
Telescope	Finding files by name or content	Fast	”Where is that file?“
nvim-tree	Exploring project structure	Medium	”What’s in this folder?”
Harpoon	Switching between active files	Instant	”Back to my main files”

Combined Workflow Example

1. Use nvim-tree to explore new project
   - Understand structure
   - Find main entry points

2. Use Telescope to find specific files
   - Search for feature implementations
   - Grep for function definitions

3. Use Harpoon for active development
   - Mark the 3-4 files you're editing
   - Quick switch while coding

4. Use Telescope for searches
   - Find references
   - Search for TODO comments

5. Back to nvim-tree for file operations
   - Create new files
   - Rename/move files

Keybindings Summary

Quick Reference

Keybinding	Action	Tool
`<leader>ff`	Find files	Telescope
`<leader>fs`	Search text	Telescope
`<leader>fr`	Recent files	Telescope
`<leader>ft`	Find TODOs	Telescope
`<leader>ee`	Toggle tree	nvim-tree
`<leader>ef`	Find in tree	nvim-tree
`<leader>ha`	Harpoon add	Harpoon
`<C-e>`	Harpoon menu	Harpoon
`<C-p>` / `<C-n>`	Harpoon nav	Harpoon

Tips and Tricks

Telescope

Use fuzzy matching: type non-contiguous letters
- “mcom” matches “MainComponent.jsx”
Use <C-q> to send results to quickfix for batch operations
Preview window shows file contents before opening

nvim-tree

Use relative numbers (<number>j/<number>k) for fast navigation
Press g? inside tree to see all keybindings
Use . to show/hide hidden files

Harpoon

Keep your list small (3-5 files) for best results
Clear your list when switching tasks
Use <C-e> to reorder files in the menu

Customization

Change Telescope Layout

Edit lua/magictt/plugins/telescope.lua:

defaults = {
  layout_strategy = "vertical",  -- or "horizontal", "center"
  layout_config = {
    width = 0.9,
    height = 0.9,
  },
}

Change nvim-tree Width

Edit lua/magictt/plugins/nvim-tree.lua:

view = {
  width = 40,  -- Change from 35 to 40
}

Add More Harpoon Keybindings

Edit lua/magictt/plugins/harpoon.lua:

-- Jump to specific positions
vim.keymap.set("n", "<leader>1", function()
  harpoon:list():select(1)
end)
vim.keymap.set("n", "<leader>2", function()
  harpoon:list():select(2)
end)

Plugin Overview

See all installed plugins

Keybindings

Complete keybinding reference

Get Started

Core Configuration

Plugins

Plugin Reference

Customization

Troubleshooting

​Fuzzy Finder: Telescope

​Features

​Keybindings

​Telescope Navigation

​Usage Workflows

​Find Files

​Search Text

​Find Under Cursor

​Recent Files

​Configuration

​FZF Native Extension

​File Explorer: nvim-tree

​Features

​Keybindings

​Open/Close

​Inside nvim-tree

​Git Status Icons

​File Operations Workflow

​Create File/Folder

​Rename File

​Delete File

​Configuration

​Quick Navigation: Harpoon

​Concept

​Features

​Keybindings

​Workflow

​Typical Harpoon Session

​Use Cases

​Configuration

​Navigation Comparison

​When to Use Each Tool

​Combined Workflow Example

​Keybindings Summary

​Quick Reference

​Tips and Tricks

​Telescope

​nvim-tree

​Harpoon

​Customization

​Change Telescope Layout

​Change nvim-tree Width

​Add More Harpoon Keybindings

​Related Documentation

Plugin Overview

Keybindings

Build docs developers (and LLMs) love

Fuzzy Finder: Telescope

Features

Keybindings

Telescope Navigation

Usage Workflows

Find Files

Search Text

Find Under Cursor

Recent Files

Configuration

FZF Native Extension

File Explorer: nvim-tree

Features

Keybindings

Open/Close

Inside nvim-tree

Git Status Icons

File Operations Workflow

Create File/Folder

Rename File

Delete File

Configuration

Quick Navigation: Harpoon

Concept

Features

Keybindings

Workflow

Typical Harpoon Session

Use Cases

Configuration

Navigation Comparison

When to Use Each Tool

Combined Workflow Example

Keybindings Summary

Quick Reference

Tips and Tricks

Telescope

nvim-tree

Harpoon

Customization

Change Telescope Layout

Change nvim-tree Width

Add More Harpoon Keybindings

Related Documentation