`jump zoxide` appears to be broken

[LeXofLeviafan]

Running yazi-0.1.5 on Linux, with zoxide-0.9.2 installed via package manager.

Pressing Z (jump fzf) in yazi switches it to a tree listing mode; pressing z (jump zoxide), however, only causes the screen to blink. Closing yazi reveals that the blinking was caused by printing out zoxide: no match found in stderr.

[sxyazi]

nix-community/home-manager#2429

Seems this is a normal behavior of zoxide. Did you just install zoxide, perhaps it hasn't been filled with any items yet

[LeXofLeviafan]

Er… Am I supposed to do something other than installing the required dependency for a builtin directory search to work? There's no indication of it in the user guide as far as I can tell, it only says Zoxide is a dependency.

[sxyazi]

for a builtin directory search to work

No, zoxide is for directory jumping as the user guide mentioned. You need fd or rg.

[LeXofLeviafan]

That is what I'm referring to. The point is, the hotkey should either work as long as the dependency is installed, or at least there should be some indication of why it doesn't and how to fix it (…at the very least the instructions on how to enable it shouldn't be missing any crucial steps).

…Incidentally, I'm also getting empty JSON preview (jq-1.7 is installed). Is it also the same kind of thing, or is it a separate bug? …How do I tell? 😅

[LeXofLeviafan]

What makes it even more confusing is that Z (jump fzf) does work out-of-the-box (just running the search when prompted)…

And if these are completely different functionalities, there's no indication of it either (…and the similar keybinding/macro naming doesn't help either)

[LeXofLeviafan]

…Though if it's a "dynamic goto database", shouldn't there be a way to manipulate it? Like, adding/removing entries from the interface? And when it's empty, there should be indication of that ("No directories to choose from").

(Also, when there's only one saved entry, it should still be displayed, instead of automatically jumping there without any visual cue.)

[sxyazi]

I think you might have misunderstood something. As I mentioned, this is how zoxide works. When you first install zoxide, it doesn't index any information. You can verify this by running zoxide query -i, and Yazi cannot intervene in this process. If you find this unreasonable, please file an issue with zoxide.

Closing as not Yazi.

[LeXofLeviafan]

This isn't an issue of how zoxide works, however; this is an issue with Yazi interface (and documentation).

• If there's no entries to choose from, it should be indicated clearly (instead of leaving it to user to guess as to "why is there nothing happening").
• If there's one entry, it should be indicated clearly as well (instead of leaving it to user to guess as to "what just happened", especially if the key press was accidental).
• And in general, the behaviour should be stable from UX standpoint. If the default behaviour is "open a dialog with saved directories, then choose one", it shouldn't deviate drastically depending on how many directories are there in the list (at least the part with opening a cancelable dialog should be retained). All of these cases can be detected by simply running zoxide query --list | wc --lines (or any equivalent thereof) before the actual query.

Not to mention that if it's working on a database, there should be a built-in way to operate it (at least adding/removing entries). Or at the very least there should be clear indication in the user guide, that "directory jumping" is fundamentally different from "path jumping" (despite even using the same macro for activation) and how to use it correctly.

[sxyazi]

There is no issue with the Yazi interface here. If you delve deeper, you'll find that Yazi directly utilizes the interface of zoxide, which in turn uses the interface of fzf. Therefore, from a fundamental perspective, it's impossible to display a dialog when there are no indexed items (please let me know if there is). Fzf itself is a fuzzy finder, and it doesn't make sense when there are no items to search for. I believe that apart from completely rewriting the interface, there is no other way to achieve this.

Regarding the documentation, zoxide is listed as optional. We assume that users will only install it if they genuinely need it and understand what it does, rather than installing it without knowing its purpose and running into issues. We are continually improving the documentation, if you come across any issues that we may have overlooked, just click "edit this page" at the bottom to edit it. 👍🏻

[LeXofLeviafan]

If you delve deeper, you'll find that Yazi directly utilizes the interface of zoxide, which in turn uses the interface of fzf. Therefore, from a fundamental perspective, it's impossible to display a dialog when there are no indexed items (please let me know if there is).

If I understand correctly, the current behaviour is to run zoxide query --interactive --exclude "$PWD" and rely on Zoxide to display it. However, there's no reason you can't run zoxide query --list --exclude "$PWD" (and count output lines) first to find out how many entries would be presented to the user. I don't think that implementing a simple alert/confirmation dialog (if you don't have one yet) for the 0/1 cases would take a lot of effort compared to the rest of the UI.

(And a hotkey for adding/removing CWD from Zoxide shouldn't take much effort either, though it'd be better UX to indicate what happened afterwards.)

Regarding the documentation, zoxide is listed as optional. We assume that users will only install it if they genuinely need it and understand what it does, rather than installing it without knowing its purpose and running into issues.

The thing is, I don't know anything about most of those tools, but I know that they're needed to enable parts of the UI. And since the purpose of these UI parts isn't particularly clear ("path jumping" only gives a vague idea of what it should mean, and it's not immediately obvious how it's any different from "directory jumping"), I try to figure it out by using the feature in the app itself instead.

So I'd suggest making this clearer for the end user in the docs; e.g. instead of "path jumping", something like "quick file subtree navigation" would be more explicit, and instead of "directory jumping", something in the lines of "bookmarked directories navigation" would also be more informative (and distinctly clearer).

…And before/unless you're going to fix the UX of the jump zoxide macro (as per my suggestion above), there should also be a note that the directory bookmarks are managed externally of the app. (A link to Zoxide docs should be helpful there, though it's not exactly helpful with DB management… and yes, I don't use cd a lot when I have an in-terminal file manager to navigate my filesystem with.)

P.S. Does zoxide --interactive actually work without fzf installed? If it's not, this should also be indicated in the user guide (since this feature would require both utilities to be installed to work).

[sxyazi]

However, there's no reason you can't run zoxide query --list --exclude "$PWD" (and count output lines) first to find out how many entries would be presented to the user. I don't think that implementing a simple alert/confirmation dialog (if you don't have one yet) for the 0/1 cases would take a lot of effort compared to the rest of the UI

This will result in continuous performance loss to provide a hint that is not even related to Yazi, only when the user first uses it after installation. I am a heavy zoxide user and do not want to pay such unnecessary performance overhead. However, I do not oppose adding it to the documentation, explicitly informing users that you need to do a cd first before use it, even though this essentially overlaps with the zoxide documentation content.

And a hotkey for adding/removing CWD from Zoxide shouldn't take much effort either, though it'd be better UX to indicate what happened afterwards

I'm not sure how this relates to the current issue. If users really need it, they can implement it themselves once the Yazi plugin system is available. If it becomes widely used, it might also become a built-in Yazi plugin that is distributed with Yazi.

The thing is, I don't know anything about most of those tools, but I know that they're needed to enable parts of the UI. And since the purpose of these UI parts isn't particularly clear ("path jumping" only gives a vague idea of what it should mean, and it's not immediately obvious how it's any different from "directory jumping"), I try to figure it out by using the feature in the app itself instead.
So I'd suggest making this clearer for the end user in the docs; e.g. instead of "path jumping", something like "quick file subtree navigation" would be more explicit, and instead of "directory jumping", something in the lines of "bookmarked directories navigation" would also be more informative (and distinctly clearer).

I agree that "quick file subtree navigation" is more clear. However, "bookmarked directories navigation" confuses me. In my view, bookmarks are something that users need to add and maintain manually. In reality, it doesn't require users to manually add "bookmarks". Instead, it automatically records these paths every time the user cd, making it more like a "history". Users typically don't need to delete certain "bookmarks" since they are automatically sorted based on usage frequency. I've been using it for a long time and haven't encountered a need to delete any "bookmarks".

…And before/unless you're going to fix the UX of the jump zoxide macro (as per my suggestion above), there should also be a note that the directory bookmarks are managed externally of the app. (A link to Zoxide docs should be helpful there, though it's not exactly helpful with DB management… and yes, I don't use cd a lot when I have an in-terminal file manager to navigate my filesystem with.)

Due to the performance issues mentioned above, I don't think that will happen. "A smarter cd command" is the official description of zoxide, and if you don't frequently use cd, I believe zoxide won't be of much help to you. After all, it's not really bookmarks; Yazi's bookmark functionality is a planned feature.

P.S. Does zoxide --interactive actually work without fzf installed? If it's not, this should also be indicated in the user guide (since this feature would require both utilities to be installed to work).

No, it will output "zoxide: could not find fzf, is it installed?", I think this is already quite clear. Is it necessary to add this to the documentation of Yazi?

[LeXofLeviafan]

This will result in continuous performance loss to provide a hint that is not even related to Yazi, only when the user first uses it after installation.

This is something that gets executed once per specific user input, not multiple times per second in a batch operation. The performance expectations are completely different here.

Besides, there's still the issue of the error message being hidden by the UI (as well as the user guide being unhelpful).

explicitly informing users that you need to do a cd first before use it

This would do absolutely nothing unless the user uses Zoxide outside of Yazi (in which case it wouldn't be necessary). And I don't know about your system, but for me it doesn't automatically start tracking my history because that would require modifying the shell rc-file(s).

…And if the intention here is to use it as a history tracker, then you'd actually have to track history; because, as it happens, users typically rely either on a file manager or on the cd command to navigate their filesystem.

I don't think that will happen

The docs still need to be fixed, one way or another.

No, it will output "zoxide: could not find fzf, is it installed?", I think this is already quite clear.

If this message is printed out the same way as "zoxide: no match found", then no, it's not clear at all (because the user won't see anything happening until he decides to close the app and unless he also pays close attention to the messages printed out in the background… and he also needs to remember that he tried to use it and it failed and there might be some clue as to why).

Is it necessary to add this to the documentation of Yazi?

Yes. This is something that is required for the feature to work, so the user should know of it at the time of installation; otherwise the information that he gets from the user guide will be incomplete (and thus incorrect).

[sxyazi]

This is something that gets executed once per specific user input, not multiple times per second in a batch operation. The performance expectations are completely different here.
Besides, there's still the issue of the error message being hidden by the UI (as well as the user guide being unhelpful).
If this message is printed out the same way as "zoxide: no match found", then no, it's not clear at all (because the user won't see anything happening until he decides to close the app and unless he also pays close attention to the messages printed out in the background… and he also needs to remember that he tried to use it and it failed and there might be some clue as to why).

Maybe we can check it only once when the user first uses Zoxide and then cache its state to avoid ongoing overhead. We can optimize it further once the Yazi plugin system is available, at which point Zoxide will be reimplemented as a plugin.

This would do absolutely nothing unless the user uses Zoxide outside of Yazi (in which case it wouldn't be necessary). And I don't know about your system, but for me it doesn't automatically start tracking my history because that would require modifying the shell rc-file(s).

To be honest, this is how I use it; it acts as a bridge between my shell and Yazi, allowing me to access directories I've previously navigated in the shell within Yazi. I installed it using Homebrew, and during the installation, Homebrew prompted me to add an integration command to my zshrc files.

The docs still need to be fixed, one way or another.
Yes. This is something that is required for the feature to work, so the user should know of it at the time of installation; otherwise the information that he gets from the user guide will be incomplete (and thus incorrect).

I've already modified fzf to be 'quick file subtree navigation' and zoxide to be 'historical directories navigation'.

https://yazi-rs.github.io/docs/installation/