README - nvim-project-marks

Minimal Neovim plugin to set file marks for specific projects.

CONTENTS

1. Introduction
2. Installation
3. Configuration
4. Usage
5. Functions
6. Troubleshooting
7. Contributing
8. License

Introduction

Using file marks is a great way to quickly jump to a specific file. By "file marks" I mean the marks you set on using m and a capital or a number (see :h mark-motions). Many great plugins exist that leverage similar strategies to jump between files, like harpoon. However, I wanted a simpler plugin that does only the following things:

• Set marks that only a apply to a specific project.
• After jumping to a mark, jump to the last cursor position in that file.

That's it, nothing more.

Installation

Use your favorite plugin manager. For example lazy.nvim:

return {
    'BartSte/nvim-project-marks',
    lazy = false,
    config = function()
        require('projectmarks').setup({})
    end
}

Lazy loading is not recommended, as the plugin may need to load another shada file than the global one. By lazy loading the plugin, this will go wrong. Note that the plugin is very small, so it will not slow down your startup time noticeably.

Configuration

The following configuration are the default and can be changed through the require("projectmarks").setup function:

require('projectmarks').setup({
  -- Set Neovim's shadafile to the given value, if it can be found by moving up
  -- the directory tree. If not, the global shada file is used.
  shadafile = 'nvim.shada',

  -- If set to true, the "'" and "`" mappings are are appended by the
  -- `last_position`, and `last_column_position` functions, respectively
  mappings = true,

  -- Message to be displayed when jumping to a mark.
  message = 'Waiting for mark...'
})

Usage

Typically, there are two strategies to manage your shada file. Locally, and grouped. The following sections explain the difference.

Locally

To set marks for specific project, you need create an empty file at the value of require("projectmarks").opts.shadafile. You can do this manually, or you can call :MakeShada. This file will keep track of the marks you set for that project. After this, you can set marks like you normally would as is described in :h mark-motions.

For example:

• You have your projects stored in the directory: ~/code
• Lets say you have the following projects:
  • ~/code/project_1/file.lua
  • ~/code/project_2/file.lua
• For each project you will have nvim.shada file:
  • ~/code/project_1/nvim.shada
  • ~/code/project_2/nvim.shada
• Also, you add a shada file to ~/code/nvim.shada.
• When you cd into ~/code/project_1 and open file.lua, the ~/code/project_1/nvim.shada will be used.
• When you cd into ~/code/project_2 and open file.lua, the ~/code/project_2/nvim.shada will be used.
• When you cd into ~/code and open ~/code/project_1/file.lua, the ~/code/nvim.shada will be used.
• When you cd into ~ and open ~/code/project_1/file.lua, the global shada will be used as there is no shada file in ~.

Grouped

This method avoids creating shada files in each project (which you have to add to your .gitignore file). Instead, you can group your shada files in a specific directory. For example:

• Create a directory, lets call it ~/shadas.
• Place the following in your config:

-- Get the name of the current working directory.
local function cwd_name()
  return vim.fn.fnamemodify(vim.fn.getcwd(), ':t')
end

require('projectmarks').setup({
  shadafile = "~/shadas/" .. cwd_name() .. ".shada"
})

• When you create a new project, create a new empty shada file in ~/shadas with the name of root directory of the project. For example, if your project is stored in ~/code/project_1, create a file called ~/shadas/project_1.shada. You can do this manually, or you can call :MakeShada.

Now, each time you open Neovim from the root of a project, the plugin will look for a shada file in ~/shadas with the name of the root directory of the project. If it finds one, it will use that file. If it does not find one, it will use the global shada file of Neovim.

Functions

The following functions are exposed:

• last_position: Jump to the last position in the file of the given mark.
• last_column_position: Jump to the last column position in the file of the given mark.
• jump_with: When using a global mark, the following will be appended to the command: {symbol}". For example, if we set symbol to symbol=', after calling a global mark A, the following command is triggered: 'A'" As, a result the cursor is returned to the last position ('") instead of the mark. As a result, you will jump to the last position in the file of the given mark.

Commands

The following commands are exposed:

• MakeShada: Create a new shada file at the path that is set in the shadafile option.

Troubleshooting

If you encounter any issues, please report them on the issue tracker at: nvim-project-marks issues

Contributing

Contributions are welcome! Please see CONTRIBUTING for more information.

License

Distributed under the MIT License.