Skip to main content

​
Overview

Global settings control Harpoon’s behavior across all projects. These are configured within the global_settings table passed to setup(): 
require("harpoon").setup({
    global_settings = {
        save_on_toggle = false,
        save_on_change = true,
        -- ... other settings
    }
})

​
All Global Settings

​
save_on_toggle

​
save_on_toggle
boolean
default:"false"
When enabled, saves marks to disk when toggling the UI menu instead of requiring :w to save manually.
When to enable:
  • You want marks saved immediately when closing the quick menu
  • You don’t want to manually save the marks file
When to disable:
  • You prefer explicit control over when marks are persisted
  • You want to review changes before saving
global_settings = {
    save_on_toggle = true  -- Auto-save on menu close
}
With save_on_toggle = false, you need to manually save the marks menu with :w before closing it to persist changes.

​
save_on_change

​
save_on_change
boolean
default:"true"
Automatically saves the harpoon file whenever marks are modified. Disabling this is not recommended.
This setting controls automatic persistence of:
  • Adding new marks with require("harpoon.mark").add_file()
  • Removing marks
  • Reordering marks
  • Updating mark positions in files
global_settings = {
    save_on_change = true  -- Recommended: keep enabled
}
Disabling save_on_change can lead to data loss. Your marks won’t be saved automatically, and you may lose them if Neovim crashes or exits unexpectedly.

​
enter_on_sendcmd

​
enter_on_sendcmd
boolean
default:"false"
When enabled, automatically presses Enter after sending a command to a terminal with sendCommand().
Behavior:
  • false: Command is typed but not executed (you can edit before running)
  • true: Command is immediately executed in the terminal
global_settings = {
    enter_on_sendcmd = true  -- Auto-execute commands
}
Example usage: 
-- With enter_on_sendcmd = false
require("harpoon.term").sendCommand(1, "npm run dev")
-- Result: "npm run dev" appears in terminal 1, waiting for Enter

-- With enter_on_sendcmd = true
require("harpoon.term").sendCommand(1, "npm run dev")
-- Result: Command executes immediately

​
tmux_autoclose_windows

​
tmux_autoclose_windows
boolean
default:"false"
Automatically closes any tmux windows created by Harpoon when you exit Neovim.
Use cases:
  • Enable: You want clean tmux sessions without leftover windows
  • Disable: You want tmux windows to persist after closing Neovim
global_settings = {
    tmux_autoclose_windows = true  -- Clean up on exit
}
This only affects tmux windows created through require("harpoon.tmux").gotoTerminal() or sendCommand(), not manually created tmux windows.

​
excluded_filetypes

​
excluded_filetypes
table
default:"{ \"harpoon\" }"
List of filetypes that should not be added to the harpoon marks list.
Common filetypes to exclude:
  • Plugin UI windows ("NvimTree", "neo-tree")
  • Fuzzy finders ("TelescopePrompt", "fzf")
  • Help files ("help")
  • Temporary buffers ("nofile", "terminal")
global_settings = {
    excluded_filetypes = {
        "harpoon",
        "NvimTree",
        "TelescopePrompt",
        "help",
        "qf"
    }
}
Why exclude filetypes: Prevents cluttering your marks with UI buffers or temporary files that you don’t want quick access to.

​
mark_branch

​
mark_branch
boolean
default:"false"
When enabled, stores marks separately for each git branch within a git repository.
How it works:
  • false: Marks are shared across all branches in a project
  • true: Each git branch has its own set of marks
global_settings = {
    mark_branch = true  -- Per-branch marks
}
Use case: You work on different features in different branches, and each feature involves a different set of files. With mark_branch = true, switching branches automatically switches to that branch’s marks.
Scenario: You’re working on two features:
  • Branch feature/auth: Files are login.tsx, signup.tsx, auth.utils.ts
  • Branch feature/dashboard: Files are dashboard.tsx, widgets.tsx, data.service.ts
With mark_branch = true:
# On feature/auth branch
git checkout feature/auth
# Your marks: login.tsx, signup.tsx, auth.utils.ts

# Switch to dashboard
git checkout feature/dashboard
# Your marks automatically switch to: dashboard.tsx, widgets.tsx, data.service.ts
With mark_branch = false, both branches share the same marks list.

​
tabline

​
tabline
boolean
default:"false"
Enables a tabline at the top of Neovim showing your harpoon marks.
global_settings = {
    tabline = true,
    tabline_prefix = "   ",
    tabline_suffix = "   "
}
Visual appearance: When enabled, shows your marked files as tabs at the top of the screen: 
   1: main.lua     2: config.lua     3: utils.lua
Customize tabline colors using these highlight groups:
  • HarpoonInactive: Inactive marks
  • HarpoonActive: Currently active mark
  • HarpoonNumberActive: Number of active mark
  • HarpoonNumberInactive: Number of inactive marks

​
tabline_prefix

​
tabline_prefix
string
default:"\" \""
String to display before each mark in the tabline.
global_settings = {
    tabline = true,
    tabline_prefix = " >> ",  -- Custom prefix
}
Result: 
 >> 1: main.lua >> 2: config.lua >> 3: utils.lua

​
tabline_suffix

​
tabline_suffix
string
default:"\" \""
String to display after each mark in the tabline.
global_settings = {
    tabline = true,
    tabline_suffix = " | ",  -- Custom suffix
}
Result: 
   1: main.lua |    2: config.lua |    3: utils.lua |

​
Complete Example

Here’s a comprehensive configuration using all global settings: 
require("harpoon").setup({
    global_settings = {
        -- Save marks when closing the quick menu
        save_on_toggle = false,
        
        -- Always save on any mark changes (recommended)
        save_on_change = true,
        
        -- Don't auto-execute terminal commands
        enter_on_sendcmd = false,
        
        -- Keep tmux windows after closing Neovim
        tmux_autoclose_windows = false,
        
        -- Prevent UI buffers from being marked
        excluded_filetypes = {
            "harpoon",
            "NvimTree",
            "neo-tree",
            "TelescopePrompt",
            "help",
            "qf",
            "fugitive"
        },
        
        -- Use per-branch marks in git repositories
        mark_branch = true,
        
        -- Show marks in tabline
        tabline = true,
        tabline_prefix = "   ",
        tabline_suffix = "   ",
    }
})

​
Accessing Global Settings

To programmatically access global settings in Lua: 
local settings = require("harpoon").get_global_settings()
print(vim.inspect(settings))
This returns the current global settings table.

​
Common Configurations

require("harpoon").setup({
    global_settings = {}
})

Build docs developers (and LLMs) love

Get started for freeTalk to us