Grapple.nvim

Showcase

Introduction

Grapple is a plugin that aims to provide immediate navigation to important files (and their last known cursor location). See the quickstart section to get started.

Goals

While Grapple shares similarities to Harpoon (and other file navigation plugins), it aims to differentiate itself in the following ways:

Frictionless first time configuration and usage (no setup, just define your keymaps and go)
Fine-grained customization of project spaces in the form of project scopes
Improved tag and scope management UI to compliment Grapple's tag/select navigation model
Ensure Grapple's public API is well-documented

Features

Persistent tags on file paths to track and restore cursor location
Scoped tags for fine-grained, per-project tagging (i.e. git branch)
Rich well-defined Grapple and Scope APIs
Toggleable windows to manage tags and scopes as a regular vim buffer
Integration with telescope.nvim
Integration with portal.nvim for additional jump options

Requirements

Neovim >= 0.9
nvim-web-devicons (optional)

Quickstart

Install Grapple.nvim using your preferred package manager
Add a keybind to tag, untag, or toggle a path. For example,

-- Lua
vim.keymap.set("n", "<leader>m", require("grapple").toggle)
vim.keymap.set("n", "<leader>M", require("grapple").toggle_tags)

-- User command
vim.keymap.set("n", "<leader>1", "<cmd>Grapple select index=1<cr>")

Next steps

Check out the example setups
Check out the default settings
View your tags with :Grapple toggle_tags
Choose a scope with :Grapple toggle_scopes
Manage your loaded scopes with :Grapple toggle_loaded
Add a statusline component
Explore the Grapple and Scope APIs

Installation

lazy.nvim

{
    "cbochs/grapple.nvim",
    dependencies = {
        { "nvim-tree/nvim-web-devicons", lazy = true }
    },
}

packer

use {
    "cbochs/grapple.nvim",
    requires = { "nvim-tree/nvim-web-devicons" }
}

vim-plug

Plug "nvim-tree/nvim-web-devicons"
Plug "cbochs/grapple.nvim"

Example Setups

Note, these examples assume you are using the lazy.nvim package manager.

Recommended

{
    "cbochs/grapple.nvim",
    opts = {
        scope = "git", -- also try out "git_branch"
    },
    event = { "BufReadPost", "BufNewFile" },
    cmd = "Grapple",
    keys = {
        { "<leader>m", "<cmd>Grapple toggle<cr>", desc = "Grapple toggle tag" },
        { "<leader>k", "<cmd>Grapple toggle_tags<cr>", desc = "Grapple toggle tags" },
        { "<leader>K", "<cmd>Grapple toggle_scopes<cr>", desc = "Grapple toggle scopes" },
        { "<leader>j", "<cmd>Grapple cycle forward<cr>", desc = "Grapple cycle forward" },
        { "<leader>J", "<cmd>Grapple cycle backward<cr>", desc = "Grapple cycle backward" },
        { "<leader>1", "<cmd>Grapple select index=1<cr>", desc = "Grapple select 1" },
        { "<leader>2", "<cmd>Grapple select index=2<cr>", desc = "Grapple select 2" },
        { "<leader>3", "<cmd>Grapple select index=3<cr>", desc = "Grapple select 3" },
        { "<leader>4", "<cmd>Grapple select index=4<cr>", desc = "Grapple select 4" },
    },
},

Harpoon

Example configuration similar to harpoon.nvim (based off of this example setup).

{
    "cbochs/grapple.nvim",
    opts = {
        scope = "git", -- also try out "git_branch"
        icons = false, -- setting to "true" requires "nvim-web-devicons"
        status = false,
    },
    keys = {
        { "<leader>a", "<cmd>Grapple toggle<cr>", desc = "Tag a file" },
        { "<c-e>", "<cmd>Grapple toggle_tags<cr>", desc = "Toggle tags menu" },

        { "<c-h>", "<cmd>Grapple select index=1<cr>", desc = "Select first tag" },
        { "<c-t>", "<cmd>Grapple select index=2<cr>", desc = "Select second tag" },
        { "<c-n>", "<cmd>Grapple select index=3<cr>", desc = "Select third tag" },
        { "<c-s>", "<cmd>Grapple select index=4<cr>", desc = "Select fourth tag" },

        { "<c-s-p>", "<cmd>Grapple cycle backward<cr>", desc = "Go to previous tag" },
        { "<c-s-n>", "<cmd>Grapple cycle forward<cr>", desc = "Go to next tag" },
    },
},

Arrow

Example configuration similar to arrow.nvim.

{
    "cbochs/grapple.nvim",
    dependencies = {
        { "nvim-tree/nvim-web-devicons" }
    },
    opts = {
        scope = "git_branch",
        icons = true,
        quick_select = "123456789",
    },
    keys = {
        { ";", "<cmd>Grapple toggle_tags<cr>", desc = "Toggle tags menu" },

        { "<c-s>", "<cmd>Grapple toggle<cr>", desc = "Toggle tag" },
        { "H", "<cmd>Grapple cycle forward<cr>", desc = "Go to next tag" },
        { "L", "<cmd>Grapple cycle backward<cr>", desc = "Go to previous tag" },
    },
},

Settings

The following are the default settings for Grapple. Setup is not required, but settings may be overridden by passing them as table arguments to the Grapple.setup function.

Default Settings

require("grapple").setup({
    ---Grapple save location
    ---@type string
    save_path = vim.fs.joinpath(vim.fn.stdpath("data"), "grapple"),

    ---Default scope to use when managing Grapple tags
    ---For more information, please see the Scopes section
    ---@type string
    scope = "git",

    ---User-defined scopes or overrides
    ---For more information about scopes, please see the Scope API section
    ---@type grapple.scope_definition[]
    scopes = {},

    ---Default scopes provided by Grapple
    ---For more information about default scopes, please see the Scopes section
    ---Disable by setting scope to "false". For example, { lsp = false }
    ---@type table<string, grapple.scope_definition | boolean>
    default_scopes = { ... }

    ---Show icons next to tags or scopes in Grapple windows
    ---Requires "nvim-tree/nvim-web-devicons"
    ---@type boolean
    icons = true,

    ---Highlight the current selection in Grapple windows
    ---Also, indicates when a tag path does not exist
    ---@type boolean
    status = true,

    ---Position a tag's name should be shown in Grapple windows
    ---@type "start" | "end"
    name_pos = "end",

    ---How a tag's path should be rendered in Grapple windows
    ---  "relative": show tag path relative to the scope's resolved path
    ---  "basename": show tag path basename and directory hint
    ---@type "basename" | "relative"
    style = "relative",

    ---A string of characters used for quick selecting in Grapple windows
    ---An empty string or false will disable quick select
    ---@type string | boolean
    quick_select = "123456789",

    ---Default command to use when selecting a tag
    ---@type fun(path: string)
    command = vim.cmd.edit,

    ---Time limit used for pruning unused scope (IDs). If a scope's save file
    ---modified time exceeds this limit, then it will be deleted when a prune
    ---requested. Can be an integer (in milliseconds) or a string time limit
    ---(e.g. "30d" or "2h" or "15m")
    ---@type integer | string
    prune = "30d",

    ---User-defined tags title function for Grapple windows
    ---By default, uses the resolved scope's ID
    ---@type fun(scope: grapple.resolved_scope): string?
    tag_title = nil,

    ---User-defined scopes title function for Grapple windows
    ---By default, renders "Grapple Scopes"
    ---@type fun(): string?
    scope_title = nil,

    ---User-defined loaded scopes title function for Grapple windows
    ---By default, renders "Grapple Loaded Scopes"
    ---@type fun(): string?
    loaded_title = nil,

    ---Additional window options for Grapple windows
    ---See :h nvim_open_win
    ---@type grapple.vim.win_opts
    win_opts = {
        -- Can be fractional
        width = 80,
        height = 12,
        row = 0.5,
        col = 0.5,

        relative = "editor",
        border = "single",
        focusable = false,
        style = "minimal",
        title_pos = "center",

        -- Custom: fallback title for Grapple windows
        title = "Grapple",

        -- Custom: adds padding around window title
        title_padding = " ",
    },
})

Usage

In general, the API is as follows:

Lua: require("grapple").{method}(...)
Command: :Grapple [method] [opts...]

Where opts in the user command is a list of value arguments and key=value keyword arguments. For example,

:Grapple cycle forward scope=cwd

Has the equivalent form

require("grapple").cycle("forward", { scope = "cwd" })

Grapple API

Grapple API and Examples

`Grapple.tag`

Create a grapple tag.

Command: :Grapple tag [buffer={buffer}] [path={path}] [index={index}] [name={name}] [scope={scope}]

API: require("grapple").tag(opts)

opts?: grapple.options

buffer?: integer (default: 0)
path?: string
index?: integer
name?: string
scope?: string

Note: only one tag can be created per scope per file. If a tag already exists for the given file or buffer, it will be overridden with the new tag.

Examples

-- Tag the current buffer
require("grapple").tag()

-- Tag a file by its file path
require("grapple").tag({ path = "some_file.lua" })

-- Tag the current buffer in a different scope
require("grapple").tag({ scope = "global" })

-- Tag the file path under the cursor
require("grapple").tag({ path = "<cfile>" })

`Grapple.untag`

Remove a Grapple tag.

API: require("grapple").untag(opts)

opts?: grapple.options (one of)

Note: Tag is removed based on one of (in order): index, name, path, buffer

Examples

-- Remove a tag on the current buffer
require("grapple").untag()

-- Remove a tag on a file
require("grapple").untag({ file_path = "{file_path}" })

-- Remove a tag on the current buffer in a different scope
require("grapple").untag({ scope = "global" })

`Grapple.toggle`

Toggle a Grapple tag.

API: require("grapple").toggle(opts)

opts?: grapple.options

Examples

-- Toggle a tag on the current buffer
require("grapple").toggle()

`Grapple.select`

Select a Grapple tag.

API: require("grapple").select(opts)

opts?: grapple.options (one of)

Note: Tag is selected based on one of (in order): index, name, path, buffer

Examples

-- Select the third tag
require("grapple").select({ index = 3 })

`Grapple.cycle`

Cycle through and select the next or previous available tag for a given scope.

Command: :Grapple cycle {direction} [opts...]

API:

require("grapple").cycle(direction, opts)
require("grapple").cycle_backward(opts)
require("grapple").cycle_forward(opts)

direction: "backward" | "forward" opts?: grapple.options (one of)

Note: Starting tag is searched based on one of (in order): index, name, path, buffer

Examples

-- Cycle to the previous tagged file
require("grapple").cycle_backward()

-- Cycle to the next tagged file
require("grapple").cycle_forward()

`Grapple.reset`

Clear all tags for a scope.

Command: :Grapple reset [scope={scope}] [id={id}]

API: require("grapple").reset(opts)

opts?: table

scope?: string scope name (default: settings.scope)
id?: string the ID of a resolved scope

Examples

-- Reset the current scope
require("grapple").reset()

-- Reset a scope (dynamic)
require("grapple").reset({ scope = "git" })

-- Reset a specific resolved scope ID
require("grapple").reset({ id = "~/git" })

`Grapple.quickfix`

Open the quickfix window populated with paths from a given scope

API: require("grapple").quickfix(opts)

opts?: table

scope?: string scope name (default: settings.scope)
id?: string the ID of a resolved scope

Examples

-- Open the quickfix window for the current scope
require("grapple").quickfix()

-- Open the quickfix window for a specified scope
require("grapple").quickfix("global")

`Grapple.exists`

Return if a tag exists. Used for statusline components

API: require("grapple").exists(opts)

returns: boolean

opts?: grapple.options (one of)

Note: Tag is searched based on one of (in order): index, name, path, buffer

Examples

-- Check whether the current buffer is tagged or not
require("grapple").exists()

-- Check for a tag in a different scope
require("grapple").exists({ scope = "global" })

`Grapple.find`

Search for a tag in a given scope.

API: require("grapple").find(opts)

returns: grapple.tag | nil, string? error

opts?: grapple.options (one of)

Note: Tag is searched based on one of (in order): index, name, path, buffer

Examples

-- Search for a tag by index in the current scope
require("grapple").find({ index = 1 })

-- Search for a named tag in a different scope
require("grapple").find({ name = "bob", scope = "global" })

Scope API

Scopes API and Examples

`Grapple.define_scope`

Create a user-defined scope.

API: require("grapple").define_scope(definition)

definition: grapple.scope_definition

Examples

For more examples, see settings.lua

-- Define a scope during setup
require("grapple").setup({
    scope = "cwd_branch",

    scopes = {
        {
            name = "cwd_branch",
            desc = "Current working directory and git branch",
            fallback = "cwd",
            cache = {
                event = { "BufEnter", "FocusGained" },
                debounce = 1000, -- ms
            },
            resolver = function()
                local git_files = vim.fs.find(".git", {
                    upward = true,
                    stop = vim.loop.os_homedir(),
                })

                if #git_files == 0 then
                    return
                end

                local root = vim.loop.cwd()

                local result = vim.fn.system({ "git", "symbolic-ref", "--short", "HEAD" })
                local branch = vim.trim(string.gsub(result, "\n", ""))

                local id = string.format("%s:%s", root, branch)
                local path = root

                return id, path
            end,
        }
    }
})

-- Define a scope outside of setup
require("grapple").define_scope({
    name = "projects",
    desc = "Project directory"
    fallback = "cwd",
    cache = { event = "DirChanged" },
    resolver = function()
        local projects_dir = vim.fs.find("projects", {
            upwards = true,
            stop = vim.loop.os_homedir()
        })

        if #projects_dir == 0 then
            return nil, nil, "Not in projects dir"
        end

        local path = projects_dir[1]
        local id = path
        return id, path, nil
    end
})

-- Use the scope
require("grapple").use_scope("projects")

`Grapple.delete_scope`

Delete a default or user-defined scope.

API: require("grapple").delete_scope(scope)

returns: string? error

scope: string scope name

`Grapple.use_scope`

Change the currently selected scope.

API: require("grapple").use_scope(scope)

scope: string scope name

Examples

-- Clear the cached value (if any) for the "git" scope
require("grapple").use_scope("git_branch")

`Grapple.clear_cache`

Clear any cached value for a given scope.

API: require("grapple").clear_cache(scope)

scope?: string scope name (default: settings.scope)

Examples

-- Clear the cached value for the initial working directory scope
require("grapple").clear_cache("static")

Scopes

A scope is a means of namespacing tags to a specific project. Scopes are resolved dynamically to produce a unique identifier for a set of tags (i.e. a root directory). This identifier determines where tags are created and deleted. Note, different scopes may resolve the same identifier (i.e. lsp and git scopes may share the same root directory).

Scopes can also be cached. Each scope may define a set of events and/or patterns for an autocommand (:h autocmd), an interval for a timer, or to be cached indefinitely (unless invalidated explicitly). Some examples of this are the cwd scope which only updates on DirChanged.

The following scopes are made available by default:

global: tags are scoped to a global namespace
static: tags are scoped to neovim's initial working directory
cwd: tags are scoped to the current working directory
lsp: tags are scoped to the root directory of the current buffer's attached LSP server, fallback: cwd
git: tags are scoped to the current git repository, fallback: cwd
git_branch: tags are scoped to the current git directory and git branch, fallback: cwd

It is also possible to create your own custom scope. See the Scope API for more information.

Examples

-- Use a builtin scope
require("grapple").setup({
    scope = "git_branch",
})

-- Define a custom scope
require("grapple").setup({
    scope = "custom",

    scopes = {
        name = "custom",
        fallback = "cwd",
        cache = { event = "DirChanged" },
        resolver = function()
            local path = vim.env.HOME
            local id = path
            return id, path
        end
    }
})

-- Disable a default scope
-- Note: be careful to disable default scopes that are used as fallbacks
require("grapple").setup({
    default_scopes = {
        lsp = false
    }
})

Grapple Windows

Popup windows are made available to enable easy management of tags and scopes. The opened buffer is given its own syntax (grapple) and file type (grapple) and can be modified like a regular buffer; meaning items can be selected, modified, reordered, or deleted with well-known vim motions. The floating window can be toggled or closed with either q or <esc>.

Tags Window

Open a floating window with all the tags for a given scope. This buffer is modifiable. Several actions are available by default:

Selection (<cr>): select the tag under the cursor
Split (horizontal) (<c-s>): select the tag under the cursor (split)
Split (vertical) (|): select the tag under the cursor (vsplit)
Quick select (default: 1-9): select the tag at a given index
Deletion: delete a line to delete the tag
Reordering: move a line to move a tag
Renaming (R): rename the tag under the cursor
Quickfix (<c-q>): send all tags to the quickfix list (:h quickfix)
Go up (-): navigate up to the scopes window
Help (?): open the help window

API:

require("grapple").open_tags(opts)
require("grapple").toggle_tags(opts)

opts?: table

scope?: string scope name
id?: string the ID of a resolved scope
style?: the style to use for the tags window

Examples

-- Open the tags window for the current scope
require("grapple").open_tags()

-- Open the tags window for a different scope
require("grapple").open_tags("global")

Scopes Window

Open a floating window with all defined scopes. This buffer is not modifiable. Some basic actions are available by default:

Selection (<cr>): open the tags window for the scope under the cursor
Quick select (default: 1-9): open the tags window for the scope at a given index
Change (<s-cr>): change the current scope to the one under the cursor
Go up (-): navigate across to the loaded scopes window
Help (?): open the help window

API:

require("grapple").open_scopes()
require("grapple").toggle_scopes()

Examples

-- Open the scopes window
require("grapple").open_scopes()

Loaded Scopes Window

Open a floating window with all loaded scope IDs. This buffer is not modifiable. Some basic actions are available by default:

Selection (<cr>): open the tags window for the loaded scope ID under the cursor
Quick select (default: 1-9): open tags window for the loaded scope ID at a given index
Toggle (<s-cr>): toggle showing both loaded and unloaded scope IDs
Unload (x): unload the tags for the scope ID under the cursor
Deletion (X): reset the tags for the scope ID under the cursor
Go up (-): navigate across to the scopes window
Help (?): open the help window

API:

require("grapple").open_loaded(opts)
require("grapple").toggle_loaded(opts)

opts?: table

all: boolean (default: false)

Examples

-- Open the loaded scopes window, show only loaded scopes
require("grapple").open_loaded()

-- Open the loaded scopes window, show both loaded and unloaded scopes
require("grapple").open_loaded({ all = true })

Window Highlights

Highlight	Default Link	Style	Used in
`GrappleBold`	N/A	`gui=bold`	Scopes window for scope names
`GrappleHint`	`Comment`	N/A	Tags window for directory hints
`GrappleName`	`DiagnosticHint`	N/A	Tags window for tag name
`GrappleNoExist`	`DiagnosticError`	N/A	Tags window for tag status
`GrappleCurrent`	`SpecialChar`	`gui=bold`	All windows for current status

Persistent State

Grapple saves all scopes to a common directory. The default directory is named grapple and lives in Neovim's "data" directory (:h standard-path). Each scope will be saved as its own individually serialized JSON blob.

By default, no scopes are loaded on startup. When require("grapple").setup() is called, the default scope will be loaded. Otherwise, scopes will be loaded on demand.

Integrations

Telescope

You can use telescope.nvim to search through your tagged files instead of the built in popup windows.

Load the extension with

require("telescope").load_extension("grapple")

Then use this command to see the grapple tags for the project in a telescope window

:Telescope grapple tags

Statusline

A statusline component can be easily added to show whether a buffer is tagged.

API:

require("grapple").statusline(opts)

opts?: grapple.statusline.options (default: settings.statusline)

icon: string (default: "󰛢")
active: string (default: [%s])
inactive: string (default: " %s")
include_icon: boolean (default: true)

Also available:

require("grapple").name_or_index()
require("grapple").exists()

Examples

require("grapple").statusline()
-- Returns "󰛢 [1] 2  3  4"

require("grapple").name_or_index()
-- Returns "1" or "bob"

-- Modify the statusline options
require("grapple").setup({
    statusline = {
        icon = "G",
        active = "|%s|",
        inactive = " %s "
    }
})

Lualine Component

Snippet

Screenshot

require("lualine").setup({
    sections = {
        lualine_b = { "grapple" }
    }
})

require("lualine").setup({
    sections = {
        lualine_b = {
            {
                require("grapple").name_or_index,
                cond = require("grapple").exists
            }
        }
    }
})

Grapple Types

Type Definitions

`grapple.options`

Options available for most top-level tagging actions (e.g. tag, untag, select, toggle, etc).

Type: table

buffer: integer (default: 0)
path: string file path or <cfile> (overrides buffer)
name: string tag name
index: integer tag insertion or deletion index (default: end of list)
scope: string scope name (default settings.scope)

`grapple.tag`

Data object for a tagged file.

Type: table

path: string absolute file path
name: string (optional) tag name
cursor: integer[] (1, 0)-indexed cursor position

`grapple.cache.options`

Options available for defining how a scope should be cached. Using the value of true will indicate a value should be cached indefinitely and is equivalent to providing an empty set of options ({}).

Type: table | boolean

event?: string | string[] autocmd event (:h autocmd)
pattern?: string autocmd pattern, useful for User events
interval?: integer timer interval
debounce?: integer debounce interval

`grapple.scope_definition`

Used for defining new scopes.

Type: table

name: string scope name
desc: string scope description
resolver: grapple.scope_resolver
fallback?: string fallback scope name
cache?: grapple.cache.options | boolean

`grapple.scope_resolver`

Used for defining new scopes. Must return a tuple of (id, path, err). If successful, an id must be provided with an optional absolute path path. If unsuccessful, id must be nil with an optional err explaining what when wrong.

Type: function

Returns: string? id, string? path, string? err

`grapple.resolved_scope`

Result from observing a scope at a point in time.

Type class

name: string scope name
id: string resolved scope ID
path: string | nil resolved scope path
:tags(): returns all tags for the given ID

Contributors

Thanks to these wonderful people for their contributions!

Inspiration and Thanks

ThePrimeagen's harpoon
stevearc's oil.nvim

Files

README.md

Latest commit

History

README.md

File metadata and controls

Grapple.nvim

Introduction

Goals

Features

Requirements

Quickstart

Installation

Example Setups

Settings

Usage

Grapple API

Grapple.tag

Grapple.untag

Grapple.toggle

Grapple.select

Grapple.cycle

Grapple.reset

Grapple.quickfix

Grapple.exists

Grapple.find

Scope API

Grapple.define_scope

Grapple.delete_scope

Grapple.use_scope

Grapple.clear_cache

Tags

Scopes

Grapple Windows

Tags Window

Scopes Window

Loaded Scopes Window

Window Highlights

Persistent State

Integrations

Telescope

Statusline

Lualine Component

Grapple Types

grapple.options

grapple.tag

grapple.cache.options

grapple.scope_definition

grapple.scope_resolver

grapple.resolved_scope

Contributors

Inspiration and Thanks

`Grapple.tag`

`Grapple.untag`

`Grapple.toggle`

`Grapple.select`

`Grapple.cycle`

`Grapple.reset`

`Grapple.quickfix`

`Grapple.exists`

`Grapple.find`

`Grapple.define_scope`

`Grapple.delete_scope`

`Grapple.use_scope`

`Grapple.clear_cache`

`grapple.options`

`grapple.tag`

`grapple.cache.options`

`grapple.scope_definition`

`grapple.scope_resolver`

`grapple.resolved_scope`