How to set up Grapple.nvim with lazy.nvim?

The README provides a recommended lazy.nvim snippet with opts, event, cmd, and keys. Copy the configuration, adjust keybinds like m for tagging, and it works out of the box.

Grapple.nvim vs Harpoon: which is better for Neovim?

Grapple.nvim offers more advanced scoping (e.g., per git branch) and a richer API, while Harpoon is simpler for basic tagging. Choose Grapple if you need project-specific namespaces and customization.

Can I use Grapple.nvim with multiple git branches in the same project?

Yes, the git_branch scope namespaces tags per branch, allowing separate tag sets. This is highlighted in the Scopes section with examples for managing different branch contexts.

How to integrate Grapple.nvim with Telescope for searching tags?

Load the extension with `require('telescope').load_extension('grapple')` and use `:Telescope grapple tags` to fuzzy-search your tagged files, as detailed in the Integrations section.

Does Grapple.nvim save tags across Neovim restarts?

Yes, tags are persistently saved to JSON files in Neovim's data directory (default: grapple folder under stdpath('data')), so they persist between sessions automatically.

How to customize the floating windows in Grapple.nvim?

Modify win_opts in settings, such as width, height, border, and highlights. The README includes a table of highlights and configurable options for tailoring the UI.

Is there a way to share grapple tags with my team?

No built-in syncing; tags are stored locally. You'd need manual solutions like symlinking save files or using version control, which can be cumbersome for team workflows.

grapple.nvim — Neovim File Tagging Plugin

What is grapple.nvim?

Grapple.nvim is a Neovim plugin that lets you tag important files and quickly navigate between them with persistent cursor positions. It solves the problem of frequently switching between key files in a project by providing a fast, scoped tagging system. Unlike basic bookmarks, it saves your exact cursor location and supports project-specific namespaces.

Target Audience

Neovim users who work on multi-file projects and need efficient navigation between frequently accessed files, such as developers, sysadmins, or technical writers using Neovim as their primary editor.

Value Proposition

Developers choose Grapple.nvim for its zero-config usability, flexible project scoping, and persistent cursor tracking. It offers a more customizable and integrated alternative to similar plugins like Harpoon, with a focus on a clean API and seamless Neovim ecosystem integration.

Overview

Neovim plugin for tagging important files

Use Cases

Best For

Quickly switching between frequently edited files in a Neovim project
Managing navigation contexts across different git branches or projects
Persisting cursor locations across editing sessions for key files
Integrating file bookmarks with Telescope for fuzzy searching
Creating custom project-specific tagging workflows with Lua APIs
Adding visual tag status indicators to your Neovim statusline

Not Ideal For

Neovim users on versions older than 0.10, as the plugin requires specific APIs introduced in that release
Projects where basic Vim marks, jumplists, or buffer navigation are sufficient for file switching needs
Teams needing shared, synchronized bookmarks across different machines or editors without manual setup

Pros & Cons

Pros

Zero-Configuration Usability

The README emphasizes 'frictionless first time configuration' with no setup required—just define keymaps to start tagging and navigating immediately.

Persistent Cursor Restoration

Tags save exact cursor positions and restore them on jumps, as noted in the Features section, making it ideal for resuming work precisely where left off.

Flexible Project Scoping

Supports dynamic scopes like git branches or custom definitions to namespace tags per project, detailed in the Scopes section, enabling fine-grained organization.

Rich API and Ecosystem

Offers well-documented Lua and command-line APIs for customization, plus integrations with Telescope.nvim and Portal.nvim, enhancing search and jump options.

Cons

Neovim Version Lock-in

Requires Neovim >= 0.10, excluding users on older versions or other editors, as stated in Requirements, limiting compatibility.

Custom Scope Complexity

Defining custom scopes involves writing Lua resolver functions, which can be challenging for users unfamiliar with Lua or Neovim's APIs, as shown in the Scope API examples.

Local-Only Persistence

Tags are saved locally in a data directory with no built-in syncing or sharing features, hindering collaboration across teams or devices without manual workarounds.

Open Source Alternative To

grapple.nvim is an open-source alternative to the following products:

h

harpoon.nvim

harpoon.nvim is a Neovim plugin for managing marks and quick navigation between important files, enhancing workflow efficiency in text editing.

grapple.nvim

What is grapple.nvim?

Overview

Use Cases

Best For

Not Ideal For

Pros & Cons

Pros

Cons

Open Source Alternative To

Frequently Asked Questions

Related Projects

Found a gem we're missing?

grapple.nvim

What is grapple.nvim?

Overview

Use Cases

Best For

Not Ideal For

Pros & Cons

Pros

Cons

Open Source Alternative To

Frequently Asked Questions

Related Projects

Found a gem we're missing?