{"id":13413021,"url":"https://github.com/gennaro-tedesco/nvim-possession","last_synced_at":"2025-04-12T18:52:25.641Z","repository":{"id":65250716,"uuid":"587669166","full_name":"gennaro-tedesco/nvim-possession","owner":"gennaro-tedesco","description":"📌 the no-nonsense session manager","archived":false,"fork":false,"pushed_at":"2025-03-19T09:36:52.000Z","size":95,"stargazers_count":265,"open_issues_count":2,"forks_count":11,"subscribers_count":1,"default_branch":"main","last_synced_at":"2025-04-10T06:21:31.442Z","etag":null,"topics":["lua","neovim"],"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/gennaro-tedesco.png","metadata":{"files":{"readme":"README.md","changelog":null,"contributing":null,"funding":null,"license":"LICENSE","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}},"created_at":"2023-01-11T09:53:04.000Z","updated_at":"2025-04-09T04:04:57.000Z","dependencies_parsed_at":"2024-01-03T03:33:51.812Z","dependency_job_id":"463bf79b-ddcf-48b1-aa74-1ae8810ecf32","html_url":"https://github.com/gennaro-tedesco/nvim-possession","commit_stats":{"total_commits":89,"total_committers":7,"mean_commits":"12.714285714285714","dds":0.4606741573033708,"last_synced_commit":"fcc6e00ffb13b7c7945560af8bf025184f795c95"},"previous_names":[],"tags_count":18,"template":false,"template_full_name":null,"repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/gennaro-tedesco%2Fnvim-possession","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/gennaro-tedesco%2Fnvim-possession/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/gennaro-tedesco%2Fnvim-possession/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/gennaro-tedesco%2Fnvim-possession/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/gennaro-tedesco","download_url":"https://codeload.github.com/gennaro-tedesco/nvim-possession/tar.gz/refs/heads/main","host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":248618237,"owners_count":21134200,"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","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":["lua","neovim"],"created_at":"2024-07-30T20:01:32.414Z","updated_at":"2025-04-12T18:52:25.618Z","avatar_url":"https://github.com/gennaro-tedesco.png","language":"Lua","funding_links":[],"categories":["Session","Lua"],"sub_categories":["Indent"],"readme":"\u003ch1 align=\"center\"\u003e\n  \u003cbr\u003e\n  \u003cimg width=\"250\" height=\"250\" src=\"https://user-images.githubusercontent.com/15387611/212337464-ef0a605f-378b-4a6f-aed2-1b6598b28348.png\"\u003e\n  \u003cbr\u003e\n  nvim-possession\n  \u003cbr\u003e\n\u003c/h1\u003e\n\n\u003ch2 align=\"center\"\u003e\n  \u003ca href=\"https://luarocks.org/modules/gennaro-tedesco/nvim-possession\"\u003e\n    \u003cimg alt=\"luarocks\" src=\"https://img.shields.io/luarocks/v/gennaro-tedesco/nvim-possession?logo=lua\u0026color=2aa198\u0026style=for-the-badge\"/\u003e\n  \u003c/a\u003e\n  \u003ca href=\"https://github.com/gennaro-tedesco/nvim-possession/releases\"\u003e\n    \u003cimg alt=\"releases\" src=\"https://img.shields.io/github/release/gennaro-tedesco/nvim-possession?logo=neovim\u0026color=2aa198\u0026style=for-the-badge\"/\u003e\n  \u003c/a\u003e\n\u003c/h2\u003e\n\n\u003ch4 align=\"center\"\u003eNo-nonsense session manager\u003c/h4\u003e\n\nYou are puzzled by neovim sessions and are not using them, are you? Start your pos-sessions journey, fear no more!\n\nThis plugin is a no-nonsense session manager built on top of [fzf-lua](https://github.com/ibhagwan/fzf-lua) (required) that makes managing sessions quick and visually appealing: dynamically browse through your existing sessions, create new ones, update and delete with a statusline component to remind you of where you are. See for yourself:\n\n![demo](https://user-images.githubusercontent.com/15387611/211946693-7c0a8f00-4ed8-4142-a8aa-a4dc75f42841.gif)\n\n## 🔌 Installation and quickstart\n\nInstall `nvim-possession` with your favourite plugin manager (`fzf-lua` is required) and invoke `require(\"nvim-possession\").setup({})`; in order to avoid conflicts with your own keymaps we do not set any mappings but only expose the interfaces, which means you would need to define them yourself. The suggested quickstart configuration is, for instance\n\n- with [lazy.nvim](https://github.com/folke/lazy.nvim)\n\n```lua\n{\n    \"gennaro-tedesco/nvim-possession\",\n    dependencies = {\n        \"ibhagwan/fzf-lua\",\n    },\n    config = true,\n    keys = {\n        { \"\u003cleader\u003esl\", function() require(\"nvim-possession\").list() end, desc = \"📌list sessions\", },\n        { \"\u003cleader\u003esn\", function() require(\"nvim-possession\").new() end, desc = \"📌create new session\", },\n        { \"\u003cleader\u003esu\", function() require(\"nvim-possession\").update() end, desc = \"📌update current session\", },\n        { \"\u003cleader\u003esd\", function() require(\"nvim-possession\").delete() end, desc = \"📌delete selected session\"},\n    },\n}\n```\n\nExposed interfaces\n\n| function            | description                                                                 | interaction                                                         |\n| :------------------ | :-------------------------------------------------------------------------- | :------------------------------------------------------------------ |\n| possession.list()   | list all the existing sessions with fzf-lua; preview shows files in session | `\u003cCR\u003e` load selected session\u003cbr\u003e`\u003cCtrl-x\u003e` delete selection session |\n| possession.new()    | prompt for name to create new session                                       | session folder must alredy exist, return a message error otherwise  |\n| possession.update() | update current session (if new buffers are open)                            | do nothing if no session is loaded                                  |\n| possession.delete() | delete current session (without prompt)                                     | do nothing if no session is loaded                                  |\n\n## 🛠 Usage and advanced configuration\n\nAs shown above the main use of the plugin is to show all existing sessions (say via `\u003cleader\u003esl`) and load the selected one upon `\u003cCR\u003e`. Once a session is loaded a global variable is defined containing the session name (to display in a statusline - see below - or to validate which session is currently active). New sessions can also be created and updated on the fly, and they will show when you next invoke the list.\n\nDefault configurations can be found in the [config](https://github.com/gennaro-tedesco/nvim-possession/blob/main/lua/nvim-possession/config.lua) and can be overriden at will by passing them to the `setup({})` function: in particular the default location folder for sessions is `vim.fn.stdpath(\"data\") .. \"/sessions/\",`. You should not need to change any of the default settings, however if you really want to do so:\n\n```lua\n\nrequire(\"nvim-possession\").setup({\n    sessions = {\n        sessions_path = ... -- folder to look for sessions, must be a valid existing path\n        sessions_variable = ... -- defines vim.g[sessions_variable] when a session is loaded\n        sessions_icon = ...-- string: shows icon both in the prompt and in the statusline\n        sessions_prompt = ... -- fzf prompt string\n    },\n\n    autoload = false, -- whether to autoload sessions in the cwd at startup\n    autosave = true, -- whether to autosave loaded sessions before quitting\n    autoswitch = {\n        enable = false -- whether to enable autoswitch\n        exclude_ft = {}, -- list of filetypes to exclude from autoswitch\n    }\n\n    save_hook = nil -- callback, function to execute before saving a session\n                    -- useful to update or cleanup global variables for example\n    post_hook = nil -- callback, function to execute after loading a session\n                    -- useful to restore file trees, file managers or terminals\n                    -- function()\n                    --     require('FTerm').open()\n                    --     require(\"nvim-tree.api\").tree.toggle()\n                    -- end\n\n    ---@type possession.Hls\n    fzf_hls = { -- highlight groups for the sessions and preview windows\n        normal = \"Normal\",\n        preview_normal = \"Normal\",\n        border = \"Todo\",\n        preview_border = \"Constant\",\n    },\n    ---@type possession.Winopts\n    fzf_winopts = {\n        -- any valid fzf-lua winopts options, for instance\n        width = 0.5,\n        preview = {\n            vertical = \"right:30%\"\n        }\n    }\n    sort = require(\"nvim-possession.sorting\").alpha_sort -- callback, sorting function to list sessions\n                                                         -- require(\"nvim-possession.sorting\").time_sort\n                                                         -- to sort by last updated instead\n})\n```\n\n### 🪄 Automagic\n\nIf you want to automatically load sessions defined for the current working directory at startup, specify\n\n```lua\nrequire(\"nvim-possession\").setup({\n    autoload = true -- default false\n})\n```\n\nThis autoloads sessions when starting neovim without file arguments (i. e. `$ nvim `) and in case such sessions explicitly contain a reference to the current working directory (you must have `vim.go.ssop+=curdir`). If more than one session in the current working directory exists, you can either specify\n\n```lua\nrequire(\"nvim-possession\").setup({\n    autoprompt = true -- default false\n})\n```\n\nto be presented with a fuzzy prompt or default automatically to load the topmost sorted session (see `sort = require(\"nvim-possession.sorting\")` in [Usage](#-usage-and-advanced-configuration)).\n\nSessions are automatically saved before quitting, should buffers be added or removed to them. This defaults to `true` (as it is generally expected behaviour), if you want to opt-out specify\n\n```lua\nrequire(\"nvim-possession\").setup({\n    autosave = false -- default true\n})\n```\n\nWhen switching between sessions it is often desirable to remove pending buffers belonging to the previous one, so that only buffers with the new session files are loaded. In order to achieve this behaviour specify\n\n```lua\nrequire(\"nvim-possession\").setup({\n    autoswitch = {\n        enable = true, -- default false\n    }\n})\n```\n\nthis option autosaves the previous session and deletes all its buffers before switching to a new one. If there are some filetypes you want to always keep, you may indicate them in\n\n```lua\nrequire(\"nvim-possession\").setup({\n    autoswitch = {\n        enable = true, -- default false\n        exclude_ft = {\"...\", \"...\"}, -- list of filetypes to exclude from deletion\n    }\n})\n```\n\nA note on lazy loading: this plugin is extremely light weight and it generally loads in no time: practically speaking there should not be any need to lazy load it on events. If you are however opting in the `autoload = true` feature, notice that by definition such a feature loads the existing session buffers in memory at start-up, thereby also triggering all other buffer related events (especially treesitter); this may result in higher start-up times but is independent of the plugin (you would get the same loading times by manually sourcing the session files).\n\n### Save-hook\n\nBefore saving a session, you can run actions that may update state or perform cleanup before updating the session.\n\nFor example, you may want to only save visible buffers to the session. This could be useful if loading a lot of buffers leads to slow startup. Or maybe you want to keep the tabline clean. To do so, you can use:\n\n```lua\nrequire(\"nvim-possession\").setup({\n    save_hook = function()\n        -- Get visible buffers\n        local visible_buffers = {}\n        for _, win in ipairs(vim.api.nvim_list_wins()) do\n            visible_buffers[vim.api.nvim_win_get_buf(win)] = true\n        end\n\n        local buflist = vim.api.nvim_list_bufs()\n        for _, bufnr in ipairs(buflist) do\n            if visible_buffers[bufnr] == nil then -- Delete buffer if not visible\n                vim.cmd(\"bd \" .. bufnr)\n            end\n        end\n    end\n})\n\n```\n\n### Post-hook\n\nAfter loading a session you may want to specify additional actions to run that may not be have been saved in the session content: this is often the case for restoring file tree or file managers, or open up terminal windows or fuzzy finders or set specific options. To do so you can use\n\n```lua\n\nrequire(\"nvim-possession\").setup({\n    post_hook = function()\n        require(\"FTerm\").open()\n        require(\"nvim-tree.api\").tree.toggle()\n        vim.lsp.buf.format()\n    end\n})\n```\n\n## 🚥 Statusline\n\nYou can call `require(\"nvim-possession\").status()` as component in your statusline, for example with `lualine` you would have\n\n```lua\n\nlualine.setup({\n    sections = {\n        lualine_a = ...\n        lualine_b = ...\n        lualine_c = {\n            { \"filename\", path = 1 },\n            {\n                require(\"nvim-possession\").status,\n                cond = function()\n                    return require(\"nvim-possession\").status() ~= nil\n                end,\n            },\n        },\n    }\n})\n```\n\nto display\n\n\u003cp align=\"center\"\u003e\n  \u003cimg width=\"300\" height=\"100\" src=\"https://user-images.githubusercontent.com/15387611/211811964-037c6233-21d6-4ee1-815c-6da068dd3595.png\"\u003e\n\u003c/p\u003e\n\nthe component automatically disappears or changes if you delete the current session or switch to another one.\n\n## Feedback\n\nIf you find this plugin useful consider awarding it a ⭐, it is a great way to give feedback! Otherwise, any additional suggestions or merge request is warmly welcome!\n","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fgennaro-tedesco%2Fnvim-possession","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Fgennaro-tedesco%2Fnvim-possession","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fgennaro-tedesco%2Fnvim-possession/lists"}