{"id":20047028,"url":"https://github.com/bartste/nvim-project-marks","last_synced_at":"2025-09-10T11:36:24.369Z","repository":{"id":176690879,"uuid":"658621622","full_name":"BartSte/nvim-project-marks","owner":"BartSte","description":"A minimal plugin for Neovim that stores file marks in a local ShaDa file.","archived":false,"fork":false,"pushed_at":"2025-05-07T16:28:42.000Z","size":67,"stargazers_count":33,"open_issues_count":0,"forks_count":0,"subscribers_count":1,"default_branch":"main","last_synced_at":"2025-09-07T08:50:01.045Z","etag":null,"topics":["neovim","neovim-configuration","neovim-lua-plugin","neovim-plugin"],"latest_commit_sha":null,"homepage":"","language":"Lua","has_issues":true,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":null,"license":"mit","status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/BartSte.png","metadata":{"files":{"readme":"README.md","changelog":"CHANGELOG.md","contributing":"CONTRIBUTING.md","funding":null,"license":null,"code_of_conduct":null,"threat_model":null,"audit":null,"citation":null,"codeowners":null,"security":null,"support":null,"governance":null,"roadmap":null,"authors":null,"dei":null,"publiccode":null,"codemeta":null,"zenodo":null}},"created_at":"2023-06-26T07:09:05.000Z","updated_at":"2025-09-03T18:16:56.000Z","dependencies_parsed_at":null,"dependency_job_id":"a8ba516a-e820-4620-a16b-c7e652f5260b","html_url":"https://github.com/BartSte/nvim-project-marks","commit_stats":null,"previous_names":["bartste/nvim-project-marks"],"tags_count":6,"template":false,"template_full_name":null,"purl":"pkg:github/BartSte/nvim-project-marks","repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/BartSte%2Fnvim-project-marks","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/BartSte%2Fnvim-project-marks/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/BartSte%2Fnvim-project-marks/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/BartSte%2Fnvim-project-marks/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/BartSte","download_url":"https://codeload.github.com/BartSte/nvim-project-marks/tar.gz/refs/heads/main","sbom_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/BartSte%2Fnvim-project-marks/sbom","scorecard":null,"host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":274455643,"owners_count":25288557,"icon_url":"https://github.com/github.png","version":null,"created_at":"2022-05-30T11:31:42.601Z","updated_at":"2022-07-04T15:15:14.044Z","status":"online","status_checked_at":"2025-09-10T02:00:12.551Z","response_time":83,"last_error":null,"robots_txt_status":"success","robots_txt_updated_at":"2025-07-24T06:49:26.215Z","robots_txt_url":"https://github.com/robots.txt","online":true,"can_crawl_api":true,"host_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub","repositories_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories","repository_names_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repository_names","owners_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners"}},"keywords":["neovim","neovim-configuration","neovim-lua-plugin","neovim-plugin"],"created_at":"2024-11-13T11:33:04.615Z","updated_at":"2025-09-10T11:36:24.317Z","avatar_url":"https://github.com/BartSte.png","language":"Lua","funding_links":[],"categories":[],"sub_categories":[],"readme":"# README - nvim-project-marks\n\nMinimal Neovim plugin to set file marks for specific projects.\n\n# CONTENTS\n\n\u003c!--toc:start--\u003e\n\n- [Introduction](#introduction)\n- [Installation](#installation)\n- [Configuration](#configuration)\n- [Usage](#usage)\n  - [Locally](#locally)\n  - [Grouped](#grouped)\n- [Commands](#commands)\n- [Functions](#functions)\n- [Lualine](#lualine)\n- [Troubleshooting](#troubleshooting)\n- [Contributing](#contributing)\n- [License](#license)\n\u003c!--toc:end--\u003e\n\n# Introduction\n\nUsing file marks is a great way to quickly jump to a specific file. By \"file\nmarks\" I mean the marks you set on using `m` and a capital or a number (see `:h\nmark-motions`). Many great plugins exist that leverage similar strategies to\njump between files, like [harpoon](https://github.com/ThePrimeagen/harpoon).\nHowever, I wanted a simpler plugin that does only the following things:\n\n- Set marks that only a apply to a specific project.\n- After jumping to a mark, jump to the last cursor position in that file.\n\nThat's it, nothing more.\n\nWell, some extra features are added later that are nice, but not essential.\n\n# Installation\n\nUse your favorite plugin manager. For example lazy.nvim:\n\n```lua\nreturn {\n    'BartSte/nvim-project-marks',\n    lazy = false,\n    config = function()\n        require('projectmarks').setup({})\n    end\n}\n```\n\nThe setup command can be called any time.\n\n# Configuration\n\nThe following configuration are the default and can be changed through the\n`require(\"projectmarks\").setup` function:\n\n```lua\nrequire('projectmarks').setup({\n  -- Set Neovim's shadafile to the given value and call `rshada!` on that value,\n  -- if it can be found by moving up the directory tree. If not, the global\n  -- shada file is used.\n  shadafile = 'nvim.shada',\n\n  -- If set to true, the following happens:\n  -- - The mapping \"'\" is appended by the `LastPosition` command.\n  -- - The mapping \"`\" is appended by the `LastColumnPosition` command.\n  -- - The `m` key, the `:mark` command, and the `:delmark` command are appended\n  --   by a function that refreshes the lualine statusline. If you do not use\n  --   this feature, nothing will happen.\n  mappings = true,\n\n  -- If set to true, the \"mark\" and \"delmarks\" command are replaced by the\n  -- \"Mark\" and \"DelMarks\" using `cnoreabbrev`. This is useful when you rely on\n  -- `lualine.marks_optimized` function, as the \"Mark\" and \"DelMarks\" commands\n  -- will refresh lualine.\n  abbreviations = false,\n\n  -- Message to be displayed when jumping to a mark. No message is displayed if\n  -- set to an empty string.\n  message = 'Waiting for mark...'\n\n  -- Message opts, table passed to nvim_notify.\n  message_opts = { timeout = 2000 }\n})\n```\n\n# Usage\n\nTypically, there are two strategies to manage your shada file. Locally, and\ngrouped. The following sections explain the difference.\n\n## Locally\n\nTo set marks for specific project, you need create an empty file at the value of\n`require(\"projectmarks\").opts.shadafile`. You can do this manually, or\nyou can call `:MakeShada`. This file will keep track of the marks you set for\nthat project. After this, you can set marks like you normally would as is\ndescribed in `:h mark-motions`.\n\nFor example:\n\n- You have your projects stored in the directory: `~/code`\n- Lets say you have the following projects:\n  - `~/code/project_1/file.lua`\n  - `~/code/project_2/file.lua`\n- For each project you will have `nvim.shada` file:\n  - `~/code/project_1/nvim.shada`\n  - `~/code/project_2/nvim.shada`\n- Also, you add a shada file to `~/code/nvim.shada`.\n- When you cd into `~/code/project_1` and open `file.lua`, the\n  `~/code/project_1/nvim.shada` will be used.\n- When you cd into `~/code/project_2` and open `file.lua`, the\n  `~/code/project_2/nvim.shada` will be used.\n- When you cd into `~/code` and open `~/code/project_1/file.lua`, the\n  `~/code/nvim.shada` will be used.\n- When you cd into `~` and open `~/code/project_1/file.lua`, the global shada\n  will be used as there is no shada file in `~`.\n\n## Grouped\n\nThis method avoids creating shada files in each project (which you have to add\nto your `.gitignore` file). Instead, you can group your shada files in a\nspecific directory. For example:\n\n- Create a directory, lets call it `~/shadas`.\n- Place the following in your config:\n\n```lua\n-- Get the name of the current working directory.\nlocal function cwd_name()\n  return vim.fn.fnamemodify(vim.fn.getcwd(), ':t')\nend\n\nrequire('projectmarks').setup({\n  shadafile = \"~/shadas/\" .. cwd_name() .. \".shada\"\n})\n```\n\n- When you create a new project, create a new empty shada file in `~/shadas`\n  with the name of root directory of the project. For example, if your project\n  is stored in `~/code/project_1`, create a file called\n  `~/shadas/project_1.shada`. You can do this manually, or you can call\n  `:MakeShada`.\n\nNow, each time you open Neovim from the root of a project, the plugin will look\nfor a shada file in `~/shadas` with the name of the root directory of the\nproject. If it finds one, it will use that file. If it does not find one, it\nwill use the global shada file of Neovim.\n\n# Commands\n\nThe following commands are exposed:\n\n- `MakeShada`: Create a new shada file at the path that is set in the `shadafile`\n  option.\n- `Mark`: The same as the `m` key and the `:mark` command, but also refreshes\n  the lualine statusline.\n- `DeleteMark`: The same as the `:delmark` command, but also refreshes the\n  lualine statusline.\n- `LastPosition`: Jump to the last position in the file of the given mark.\n- `LastColumnPosition`: Jump to the last column position in the file of the\n  given mark.\n\nFor convenience, you can set the `abbreviations` option to `true` such that the\n`:mark` and `:delmark` commands will be changed to `:Mark` and `:DeleteMark`.\n\n# Functions\n\nThe following functions are exposed through the `require(\"projectmarks\")`\nmodule.\n\n- `jump_with`: When using a global mark, the following will be appended to the\n  command: {symbol}\". For example, if we set symbol to `symbol='`, after calling\n  a global mark `A`, the following command is triggered: `'A'\"` As, a result the\n  cursor is returned to the last position ('\") instead of the mark. As a result,\n  you will jump to the last position in the file of the given mark.\n- The functions: `make_shada`, `add_mark`, `delete_mark`, `last_position`, and\n  `last_column_position` are also exposed. They are equivalent to the commands,\n  only now no notifications are displayed.\n\nIt is not recommended to use functions from other modules, as they are may be\nsubject to change, with the exception of the `require(\"projectmarks\").lualine`\nmodule, as is explained in the next section.\n\n# Lualine\n\nFor those using lualine, the following tables can be used for lualine:\n\n- `require('projectmarks').lualine.shada`: Displays an icon with the name of the\n  shada file that is being used. If the global shada file is used, nothing is\n  displayed.\n- `require('projectmarks').lualine.marks`: Displays the marks that are set in\n  the current buffer. If no marks are set, nothing is displayed.\n- `require('projectmarks').lualine.marks_optimized`: Has the same functionality\n  as `marks`, but it only refreshes its content when the active buffer changes,\n  or the marks are changed. The `opts.mapping` option must be set to `true` for\n  this to work.\n\n# Troubleshooting\n\nIf you encounter any issues, please report them on the issue tracker at:\n[nvim-project-marks issues](https://github.com/BartSte/nvim-project-marks/issues)\n\n# Contributing\n\nContributions are welcome! Please see [CONTRIBUTING](./CONTRIBUTING.md) for\nmore information.\n\n# License\n\nDistributed under the MIT License.\n","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fbartste%2Fnvim-project-marks","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Fbartste%2Fnvim-project-marks","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fbartste%2Fnvim-project-marks/lists"}