Feature: System of default and common keybinds

[timsofteng]

Hello. I was really impressed by telescope.

I have several ideas how to improve it and pickers which I will try to describe in this and another issues.

KEYBINDING

In my opinion keybinding is very important part in software development. It's not only the thing which everyone can customize. It's part of architecture and philosophy of soft. Especially for telescope which architecture (ecosystem of pickers) is complex and modular.
My idea is that the main keyboard shortcuts should be consistent from picker to picker.
I guess it's necessary to design picker's feature with a look at the common shortcuts

That's why I want to introduce you my ideas of common shortcuts and hope we all can discuss about it. Some of them I have seen in another applications and other I just design by myself.

(note I will mention keys in normal mode which means for insert mode we just should add ctrl key to shortcuts)

LIST OF BINDS

movements

1. Down (next) - j.
2. Up (previous) - k.
3. Back - h.
4. Forward - l.

It's very traditional vim movement. Back and forward actions could be used in file browser to change directory or go to higher level. Or from git branch to the list of commits and back (it's something like pickers chain which I'll try to describe in the next issue (#618)). Also back key can clean up all from search field at first if it's not the mpty.

Additionally we will have empty n and p keys which we can use in another useful actions. E.g press n in file browser to create file or directory which you can choose in addition dialog in the vim' bottom Press f to create file, press d to create directory, press b to create bookmark (#620). It's kind of nnn's FM working.
Another example is press n to create new git branch etc.
P key we can you to paste something (commits cherry picking, files in file browser).

go up one level in the filesystem

Press backspace to go up one level from current directory. The difference between backspace and h is that with h you can't go up if this level is out of scope of your working directory. With backspace you will can. BUT without cwd. (Check how fern.vim works, it's same).

change working directory ("cwd")

** or ~`. Just press it to change working directory (e.g in file browser)

mark all searched instances

I'm not sure is it bind exists or not but something like a key to mark all will be fine.

disable ESC

Escape key can be used as closed of some deep sub-actions of pickers. I guess it's more useful.
Close telescope by ctrl-c

deletion

Simple d key. When you need to remove something just press d.

hidden files

Just press . (dot) to enable dot files in pickers (file browser, file picker, etc)

Open files or directories in external program

Press O key. Imagine you want to open image from you project or something else.
You just need to find file in some of pickers and press o. Then I suggest to open all user's binaries and sorted it's from associated with type bof file at the top. So if you want open .html file in browser you press o and telescope open binaries list with browser at first. Press enter and file will be opened in browser.

info key

I'm not sure, maybe ? key. For additional information of file, some of git object or whatever. Press "?" will print some info or meta information about instance in preview window and immediately move cursor to preview window (j-k to move inside). Then press ESC to back to regular picker's functionality.

bookmarks

'-key. Marks for file system. I can describe this feature in separate issue (#620) but in general it means quick jump to some important or most visited location of file system. Just press ' and then press a sign of bookmark in dialog window and picker which already opened will start work from that place without cwd.

That's all what I have for now.
Hope to receive feedback.
Thanks.

[Conni2461]

Wow there is a lot of stuff. Let me unpack it. First of all we have a System of default and common keybindings. These are the default keybindings and i think they are pretty useful :)

Also a lot of these things are really specific to file_browser 😆

Forward - l

You can just map l to default_select

Back - h or backspace

Little bit trickier to map this in file_browser because it would need to refresh the picker and that function is local. But we could maybe just map it for you @elianiva
You can also limit this by cwd should be just an if. Not really hard.

Additionally we will have empty n and p keys which we can use in another useful actions. E.g press n in file browser to create file or directory which you can choose in addition dialog in the vim' bottom Press f to create file, press d to create directory

Funny we already have this. Just write new file into prompt this/is/new/file.lua or this/is/new/dir/ and press <c-e> and i actually like this workflow. If it ends with / it will create a new directory otherwise a new file. And it works recursive even if you don't have the file created.

bookmark

Everything about bookmarks is out of scope in my opinion. And we have the project extension for this. But a way to inject mappings into builtins isn't so that extension could do this, but this requires an interface in telescope core.

You mention a lot of actions that are missing, like create branch (good idea). You can try to write them yourself in your config and then upstream it. It shouldn't be that hard but we just need more time to make docgen more stable so we can actually document these actions. They are not useful if nobody knows about them 🤣

mark all searched instances

Whats the usecase of mark all. Currently our multiselection only works with send_to_qflist and we already have a function that sends all to qflist. We can talk about a mark if we finished multi selection which is pretty hard because an action can basically be anything (because it can be replaced)

disable ESC

We are probably not changing any current default mappings. We have (potentially) 1.1k users and i don't wanna make anyone made because we changed a mapping. Also i have no idea what a sub-action is.

deletion

<c-d> is already preview scrolling for all pickers that have a previewer. Also i kinda also have a bad feeling about mapping deletion because of how dangerous it can be.

hidden files

We would need to refresh it. file_browser can refresh find_files can't because its an oneshot_job and we haven't figured out how some things should continue with them. Especially with the upcoming async work.

Open files or directories in external program

If you need that (i kinda think its not that useful) you can write your own action that just does xdg-open. And side note one core member is working on a google/duckduckgo/stackoverflow/whatever you can imagine search extension that will do xdg-open on select.

info key

I am almost done with cycling previewers, which allow different views on a problem. #528 So for example you can have a diff to parent, diff to head, git show and git message. You can either use the defaults or change order, remove one or more, or just add your own previewer. Which is pretty cool :)

[elianiva]

Also i kinda also have a bad feeling about mapping deletion because of how dangerous it can be.

yah this is dangerous, I accidentally deleted my entire directory when I was working on the file browser 🤣
the confirmation prompt which shows the selected files was borked, so I didn't know that I selected all of my files.
But now it should be good (fingers crossed)

If you need that (i kinda think its not that useful) you can write your own action that just does xdg-open

yep, and don't forget to discard the output using &>/dev/null because it sometimes throws a random text that ruins your neovim UI.

Back - h or backspace

this could be good, I usually spammed ../ to go up a directory but sometimes I got carried away and went too far up leaving my project root directory.

but in general it means quick jump to some important or most visited location of file system

if you want to do this, the best solution atm is telescope-frecency. You can define a tag (forgot what it's called) for a directory which you can filter out by doing :tag_name: your query goes here and it will only show the files that is in that directory. The downside of this is you define the tag manually in your config.

[timsofteng]

Funny we already have this. Just write new file into prompt this/is/new/file.lua or this/is/new/dir/ and press <c-e> and i actually like this workflow. If it ends with / it will create a new directory otherwise a new file. And it works recursive even if you don't have the file created.

Oh, it's great. I didn't know about / trick fro directories.

You mention a lot of actions that are missing, like create branch (good idea). You can try to write them yourself in your config and then upstream it. It shouldn't be that hard but we just need more time to make docgen more stable so we can actually document these actions. They are not useful if nobody knows about them

Whats the usecase of mark all.

In git_status it can work like "stage all" or in file browser "open all" or "delete all" or whatever.

hidden files

We would need to refresh it. file_browser can refresh find_files can't because its an oneshot_job and we haven't figured out how some things should continue with them. Especially with the upcoming async work.

So picker would be refreshed. I suppose it's not a problem. But user can work with hidden files without additional config tweaking.

info key

I am almost done with cycling previewers, which allow different views on a problem. #528 So for example you can have a diff to parent, diff to head, git show and git message. You can either use the defaults or change order, remove one or more, or just add your own previewer. Which is pretty cool :)

Cool! Can I jump between previewers on the fly?

[timsofteng]

Also i kinda also have a bad feeling about mapping deletion because of how dangerous it can be.

yah this is dangerous, I accidentally deleted my entire directory when I was working on the file browser
the confirmation prompt which shows the selected files was borked, so I didn't know that I selected all of my files.
But now it should be good (fingers crossed)

Hope it will not a problem with it. With conformation promt it's pretty safety. Or we can map it to capital D which is harder to use with ctrl but less dangerous :)

If you need that (i kinda think its not that useful) you can write your own action that just does xdg-open

yep, and don't forget to discard the output using &>/dev/null because it sometimes throws a random text that ruins your neovim UI.

Could you please implement this feature to file browser? To be honest I'm not good in lua :-)

Back -h or backspace

this could be good, I usually spammed ../ to go up a directory but sometimes I got carried away and went too far up leaving my project root directory.

Yep. I mean press "h" could do "up one level" unless we reach root working directory. And then if we want to go up but without "cwd" we could just press backspace and it allow go up despite of non working directory. Is it make sence?

Also we can map something to go to root of working directory if it is necessary.

but in general it means quick jump to some important or most visited location of file system

if you want to do this, the best solution atm is telescope-frecency. You can define a tag (forgot what it's called) for a directory which you can filter out by doing :tag_name: your query goes here and it will only show the files that is in that directory. The downside of this is you define the tag manually in your config.

I will check this plugin. Thanks.

[Conni2461]

I didn't know about / trick fro directories.

Thats why i spend almost every free minute last week on making out docgen system better 😆

stage all, etc

We can talk about this if we have figured out how to run action.select_* with multiselection :)

jump between previewers on the fly?

You mean like <c-1> to first, <c-3 to third if exist? Could add this :) thanks for the suggestion. Is a good one :)

hidden on dot, h and l, <bs> and xdg-open

if @elianiva wants he can do all of the above in his PR where he implements copy, move, etc :) Shouldn't be that hard :)

[timsofteng]

We can talk about this if we have figured out how to run action.select_* with multiselection :)

if @elianiva wants he can do all of the above in his PR where he implements copy, move, etc :) Shouldn't be that hard :)

Got it.

You mean like to first, <c-3 to third if exist? Could add this :) thanks for the suggestion. Is a good one :)

It's exactly what I mean.

[GitMurf]

I am not sure if this is appropriate to ask this here but saw it was still Open and thought it better than opening up a new gh issue for arguably more of a question than a request.

My question is, when adding to the default keymaps for Telescope, I have a function where I do the following. I am trying to toggle on / off result wrapping. This seems to work but you have to close out of telescope and re-activate a new instance / search etc. (whatever you were doing in telescope).

My question is:

1. Does this work or do you advise against this?
2. Is there a way I can do this but "on the fly" so it would apply the wrapping or remove the wrapping when i do <c-w>?
3. If 2 is not possible, is there some way I can "reload" / "re-render" the current Telescope picker so that it applies the changes so I do not have to redo the Telescope picker again for the change to apply?
4. While my use case right now is for toggling the results wrapping, ultimately I would love the ability to do this kind of thing for any Telescope config/option.

Thoughts? Thanks in advance!

local toggle_wrap_result_items = function()
  local optsValues = require("telescope.config").values
  local wrap_results_current = optsValues.wrap_results
  require("telescope").setup({
    defaults = {
      wrap_results = not wrap_results_current,
    },
  })
  vim.notify(
    "Telescope > Changed wrap_results to: "
      .. tostring(not wrap_results_current)
      .. ". Will take effect after re-running your Telescope command / picker."
  )
end

-- ... other telescope config stuff

-- later in config I set the telescope keymap with this
["<C-w>"] = toggle_wrap_result_items,

[jamestrew]

@GitMurf
To answer your questions:

1. calling setup multiple times should probably avoided.
2. and 3. you achieve this like so. Here I'm just getting the window id of the results window and directly manipulating the wrap setting. The "refreshing" with picker:refresh happens to be necessary here. I could probably guess but I didn't dive into why this is the case. Just noticed it wasn't rendering quite right so I added the refresh call. Seems to help.

require("telescope").setup({
  defaults = {
    mappings = {
      i = {
        ["<C-w>"] = function(prompt_bufnr)
          local picker = require("telescope.actions.state").get_current_picker(prompt_bufnr)
          local result_winid = picker.results_win
          local wrap = vim.api.nvim_win_get_option(result_winid, "wrap")
          vim.api.nvim_win_set_option(result_winid, "wrap", not wrap)
          picker:refresh(nil, { multi = picker._multi })
        end,
      },
    },
  },
})

4. Check out developers.md - has some more info on more "advanced" uses for telescope.

[GitMurf]

2. and 3. you achieve this like so. Here I'm just getting the window id of the results window and directly manipulating the wrap setting. The "refreshing" with picker:refresh happens to be necessary here. I could probably guess but I didn't dive into why this is the case. Just noticed it wasn't rendering quite right so I added the refresh call. Seems to help.

Ahhh ok very nice. Thank you! This is the route I started but could not get it to apply / render! The picker refresh is what I needed. Thanks a lot @jamestrew !

[GitMurf]

@jamestrew just wanted to confirm I got this working thanks to your advice above. Thanks a lot! FYI I did not have to use the picker:refresh at the end of the code you provided. It seemed to work fine without it. Also I replaced the deprecated functions for options/values with the new ones and updated my final working solution below:

...
      local picker = require("telescope.actions.state").get_current_picker(prompt_bufnr)
      local result_winid = picker.results_win
      local wrap = vim.api.nvim_get_option_value("wrap", { win = result_winid })
      vim.api.nvim_set_option_value("wrap", not wrap, { win = result_winid })
...