Notice of upcoming breaking change regarding git branches

[olimorris]

tl;dr

1. If you're using persisted.nvim in a non-git enabled repo, the latest update (66d540f) will stop you loading your session files
2. This is because I'm unwinding a dumb design decision I made a while back
3. The fix is to remove @@main from the names of your sessions which belong to a non-git enabled repo
4. If you go to the How to fix section below, you'll see how you can do this

Background

The inability of persistence.nvim to enable sessions per git branch was what lead to me creating persisted.nvim. For my workflow, it's a feature I can't live without.

This feature works by sandwiching the branch name between @@ and the .vim extension in the session's file name. So %Users%Oli%Code%Neovim%persisted.nvim@@main.vim is the name of my local persisted.nvim repo on the main branch. The use of @@ is simply because it's an uncommon pattern to find across any file system. When a user attempts to load a session, it's somewhat trivial for the plugin to workout what session the user actually wishes to load.

This all works great. Except that well over 18 months ago (a156dd3), I made a poor design decision. In hindsight I'd say dumb. And it's that design decision that I write about in this post.

Whilst implementing Telescope support, I decided that any non-git enabled repo should have a branch of main appended to it. I struggle to recall my logic for that. Perhaps I was thinking if it does become a git enabled repo then the user can carry over their existing session file given the branch will likely be called main. Regardless of that, it was silly and ultimately leads to a non-truthy session name. I can't be bothered to find the issues or discussions, but a number of you raised this point further down the line and by then I became concerned about breaking functionality for existing users so I did nothing.

Taking a break from a plugin and then returning, is one of the best ways to gain some clarity of thought on its direction and how it can be improved. After this "moment of clarity" and recognising some improvements to the plugin's Telescope support, I've come to realise I need to unwind from my "poor design decision".

That is, stop non-git enabled repo's from having @@main appended to them.

So starting from 66d540f, anyone who is using the plugin to manage sessions for a non-git enabled repository will need to remove @@main from the file name.

How to fix

There's a couple of options:

Manually rename the session file

1. Go to ~/.local/share/nvim/sessions (or wherever you save your sessions to)
2. Locate the session file
3. Rename it to remove @@main from the filename

Use the plugin to remove the git branch from the session

1. Ensure you've enabled Telescope support in the plugin
2. Run :Telescope persisted
3. Find the session you wish to modify and press <C-b> to change the branch
4. Don't enter any value and press <CR> twice

Final words

One of my annoyances with Neovim plugins is how breaking changes are communicated to users. I've lost countless hours trying to hunt down the cause of some weird issue all because a plugin author couldn't be bothered to put a conditional check and an vim.api.nvim_echo call.

For this breaking change, hopefully you've been redirected to this announcement from the plugin itself and it's not been too laborious to correct. But my sincere apologies for making you spend your valuable time on a trivial issue which was completely preventable!

_Oli

[adrian5]

Thanks for the heads-up Oli!

[miversen33]

Very well written. It can be tough to admit, own and fix a mistake. Especially when you know that mistake has a high chance of breaking space bar heating. Even so, this is very well communicated and your last point

One of my annoyances with Neovim plugins is how breaking changes are communicated to users. I've lost countless hours trying to hunt down the cause of some weird issue all because a plugin author couldn't be bothered to put a conditional check and an vim.api.nvim_echo call.

is so true it hurts. I get so damned irritated when I do an update and suddenly all my shit is broken because a maintainer decided to make some configuration change that nukes older instances of the code and all there is an "oopsy doopsy" in the specific commit lol.

Thank you for this, even if it does break stuff. It is better to rip the bandaid off. If users truly don't want to fix this issue, there is nothing preventing them from pinning to the specific commit before you fixed this. The important thing is that you called this out so people know about it.