• Stars
    star
    203
  • Rank 188,466 (Top 4 %)
  • Language
    Lua
  • License
    MIT License
  • Created about 3 years ago
  • Updated about 2 months ago

Reviews

There are no reviews yet. Be the first to send feedback to the community and the maintainers!

Repository Details

🦘 Jump into the repositories (git, mercurial…) of your filesystem with telescope.nvim, without any setup

🦘 telescope-repo.nvim: jump around the repositories in your filesystem, without any setup

Neovim version GitHub tag (latest SemVer)

telescope-repo is an extension for telescope.nvim that searches the filesystem for git (or other SCM1, like Pijul, Mercurial…) repositories. It does not require any setup: the list of repositories is built on the fly over your whole $HOME, you don’t need to manually add projects or open some folders to populate this list, as opposed to telescope-project.nvim or project.nvim.

Finding the repositories with “telescope” in their name, with the README in the panel on the top

Use cases include:

  • If you don’t start vim from the shell (from a GUI or as the start command of a terminal), you are most likely in your $HOME directory. You then want to jump into your code as quickly as possible and this plugin can help!
  • Sometimes, you have the definition of a function and use of it in different repositories (e.g. a library you wrote and a program using this library). This plugin helps to open the two, for instance in two splits.
  • Use of less popular SCMs: some similar extensions rely on strong conventions to find repositories, like “directories containing a .git file that is also a directory, all inside directory X”. Less popular SCMs like Pijul have a different folder name, and even git worktrees don’t fit neatly into these constraint, with their .git files.

telescope-repo.nvim is based on telescope-ghq.nvim

Installation

You need to add these in your plugin management system2:

'nvim-lua/plenary.nvim'
'nvim-telescope/telescope.nvim'
'cljoly/telescope-repo.nvim'

And optionally, to load the extension:

require'telescope'.load_extension'repo'

A handy companion plugin is vim-rooter, as it’ll change the current directory according to the current file’s detected project (often, the root of the git repository). To get it to change each buffer’s directory, instead of the whole editor by default, add the following Lua to your configuration:

g['rooter_cd_cmd'] = 'lcd'

Packer

For instance, with Packer.nvim:

use 'cljoly/telescope-repo.nvim'
use {
  'nvim-telescope/telescope.nvim',
  requires = { {'nvim-lua/plenary.nvim'} }
}

External Dependencies

Required

  • fd to find the repositories on the filesystem with list
  • plocate, lolcate-rs or locate to find the repositories on the filesystem with cached_list

Optional

  • glow to preview markdown files, will fall back to bat if not present (and uses cat if neither are present)

Usage

Global Configuration

You can change the default argument given to subcommands (like list or cached_list) using the telescope setup function with a table like this:

{
  extensions = {
    repo = {
      <subcommand> = {
        <argument> = {
          "new",
          "default",
          "value",
        },
      },
      settings = {
        auto_lcd = true,
      }
    },
  },
}

for instance, you could do:

require("telescope").setup {
  extensions = {
    repo = {
      list = {
        fd_opts = {
          "--no-ignore-vcs",
        },
        search_dirs = {
          "~/my_projects",
        },
      },
    },
  },
}

require("telescope").load_extension "repo"

Note: make sure to have require("telescope").load_extension "repo" after the call to require("telescope").setup {…}, otherwise the global configuration won’t be taken into account.

list

:Telescope repo list or lua require'telescope'.extensions.repo.list{}

Running repo list and list repositories' paths.

key action
<CR> (edit) builtin.git_files for git, falls back to builtin.find_files for other SCMs
<C-v> (vertical) builtin.live_grep in the selected project
<C-t> (tab) Same as <CR> but opens a new tab. Also, does a cd into the project’s directory for this tab only

Options

bin

Filepath for the binary fd.

" path can be expanded
:Telescope repo list bin=~/fd
pattern

Pattern of the SCM database folder.

Default value: [[^\.git$]]

cwd

Transform the result paths into relative ones with this value as the base dir.

Default value: vim.fn.getcwd()

fd_opts

This is a relatively advanced option that you should use with caution. There is no guarantee that a particular set of options would work the same across multiple versions

This passes additional options to the command fd that generates the repository list. It is inserted like so:

fd [set of default options] [fd_opts] --exec [some default command] [pattern] …
Example

Let’s say you have a git repository S inside another git repository M (for instance because of #5), but S is in a directory that’s ignored in the .gitignore in M. S wouldn’t appear in the Telescope list of this extension by default, because it is ignored (.gitignore are taken into account by default).

To avoid taking into account the .gitignore, we need to pass --no-ignore-vcs to fd, like so (in NeoVim):

:lua require'telescope'.extensions.repo.list{fd_opts={'--no-ignore-vcs'}}

This will list M and S in the Telescope output! The downside is that listing repositories will be a little longer, as we don’t skip the git-ignored files anymore.

search_dirs

This limits the search to a particular directory or set of directories.

Example
:lua require'telescope'.extensions.repo.list{search_dirs = {"~/ghq/github.com", "~/ghq/git.sr.ht"}}
:lua require'telescope'.extensions.repo.list{search_dirs = {"~/.local/share/nvim/site/pack"}}
tail_path

Show only basename of the path.

Default value: false

shorten_path

Call pathshorten() for each path. This will for instance transform /home/me/code/project to /h/m/c/project.

Default value: false

Examples

Here is how you can use this plugin with various SCM:

SCM Command
git :Telescope repo list or lua require'telescope'.extensions.repo.list{}
pijul lua require'telescope'.extensions.repo.list{pattern=[[^\.pijul$]]}
hg lua require'telescope'.extensions.repo.list{pattern=[[^\.hg$]]}
fossil lua require'telescope'.extensions.repo.list{pattern=[[^\.fslckout$]]}

Is your favorite SCM missing? It should be straightforward to support it by changing the pattern parameter. If you want it to be considered for addition here, open a PR!

cached_list

:Telescope repo cached_list

This relies on a locate command to find repositories. This should be much faster than the list command, as it relies on a pre-built index but results may be stalled.

Note: at this point, the plugin does not manage index update. Updating the index often requires to run a command like updatedb as root.

Notes for MacOS

glocate command used for caching on MacOS comes with gnu findutils which can be installed with

brew install findutils

With glocate installed use, add the following to your .bashrc/.zshrc

# https://egeek.me/2020/04/18/enabling-locate-on-osx/
if which glocate > /dev/null; then
  alias locate="glocate -d $HOME/locatedb"

  # Using cache_list requires `LOCATE_PATH` environment var to exist in session.
  # trouble shoot: `echo $LOCATE_PATH` needs to return db path.
  [[ -f "$HOME/locatedb" ]] && export LOCATE_PATH="$HOME/locatedb"
fi

alias loaddb="gupdatedb --localpaths=$HOME --prunepaths=/Volumes --output=$HOME/locatedb"

After you have run loaddb the first time you need to reload the shell to make sure that it exports the LOCATE_PATH variable. Then the following command should work:

lua require'telescope'.extensions.repo.cached_list()

If nothing is shown, even after a little while, try this:

lua require'telescope'.extensions.repo.cached_list{locate_opts={"-d", vim.env.HOME .. "/locatedb"}}

Note: Installation and use of the plugin on systems other than GNU/Linux is community-maintained. Don't hesitate to open a discussion or a pull-request if something is not working!

TODO cached_list

Provide instructions on how to setup periodic update of the locate database.

Troubleshooting

You should try to run:

sudo updatedb

if you encounter any problems. If it’s not the case by default, you should automate such index update with for instance cron or systemd-timers. See https://wiki.archlinux.org/title/Locate.

Options

Options are the similar to repo list, bearing in mind that we use locate instead of fd. Note that the following list options are not supported in cached_list:

  • fd_opts, as we don’t use fd with cached_list,
  • search_dirs, as locate does not accept a directory to search in.

Examples

Exclude Irrelevant Results

Chances are you will get results from folders you don’t care about like .cache or .cargo. In that case, you can use the file_ignore_patterns option of Telescope, like so (these are Lua regexes).

Hide all git repositories that may be in .cache or .cargo:

:lua require'telescope'.extensions.repo.cached_list{file_ignore_patterns={"/%.cache/", "/%.cargo/"}}
Notes
  • These patterns are used to filter the output of the locate command, so they don’t speed up the search in any way. You should use them mainly to exclude git repositories you won’t want to jump into, not in the hope to enhance performance.
  • The %. in Lua regex is an escaped . as . matches any characters.
  • These patterns are applied against whole paths like /home/myuser/.cache/some/dir, so if you want to exclude only /home/myuser/.cache, you need a more complicated pattern like so:
:lua require'telescope'.extensions.repo.cached_list{file_ignore_patterns={"^".. vim.env.HOME .. "/%.cache/", "^".. vim.env.HOME .. "/%.cargo/"}}
Use With Other SCMs

Here is how you can use this plugin with various SCM (we match on the whole path with locate, so patterns differ slightly from repo list: notice the ^ that becomes a /):

SCM Command
git :Telescope repo list or lua require'telescope'.extensions.repo.list{}
pijul lua require'telescope'.extensions.repo.list{pattern=[[/\.pijul$]]}
hg lua require'telescope'.extensions.repo.list{pattern=[[/\.hg$]]}
fossil lua require'telescope'.extensions.repo.list{pattern=[[/\.fslckout$]]}

FAQ

No repositories are found

Make sure that :checkhealth telescope shows something like:

## Telescope Extension: `repo`
  - OK: Will use `glow` to preview markdown READMEs
  - OK: Will use `bat` to preview non-markdown READMEs
  - OK: locate: found `plocate`
    plocate 1.1.13
    Copyright 2020 Steinar H. Gunderson
    License GPLv2+: GNU GPL version 2 or later <https://gnu.org/licenses/gpl.html>.
    This is free software: you are free to change and redistribute it.
    There is NO WARRANTY, to the extent permitted by law.
  - INFO: Repos found for `:Telescope repo cached_list`:
    /home/cj/.cache/yay/android-sdk/.git, /home/cj/.cache/yay/android-sdk-platform-tools/.git...
  - OK: fd: found `fd`
    fd 8.3.0
  - INFO: Repos found for `:Telescope repo list`:
    /home/cj/tmp/git_rst, /home/cj/qmk_firmware...

This may take a few seconds to run

The output of this command may point to missing dependencies.

Getting the repository list is slow

If :Telescope repo list is slow, you can use your .fdignore to exclude some folders from your filesystem. You can even use a custom ignore file with the --ignore-file option, like so:

lua require'telescope'.extensions.repo.list{fd_opts=[[--ignore-file=myignorefile]]}

Contribute

Contributions are welcome, see this document!

The telescope developers documentation is very useful to understand how plugins work and you may find these tips useful as well.

Running tests

Plenary.nvim integration tests are executed as a part of the CI checks. However, they are very basic for now and you might be better off just testing the two commands locally.

Code Formatting & Linting

StyLua is used for code formatting. It is run like so:

make fmt

To run the linter:

make lint

Acknowledgement

I would like to thank all the contributors to this plugin, as well as the developers of neovim and Telescope. Without them, none of this would be possible.

Thanks to Code Smell for demoing the plugin in 5 Terrific Neovim Telescope Extensions for 2022 🔭.

Furthermore, thanks to Migadu for offering a discounted service to support this project. It is not an endorsement by Migadu though.

Stability

We understand that you need a reliable plugin that never breaks. To this end, code changes are first tested on our machines in a separate dev branch and once we are reasonably confident that changes don’t have unintended side-effects, they get merged to the master branch, where a wider user-base will get the changes. We also often tag releases, holding a more mature, coherent set of changes. If you are especially sensitive to changes, instruct your package manager to install the version pointed by a particular tag and watch for new releases on GitHub or via RSS. Conversely, if you wish to live on the bleeding-edge, instruct your package manager to use the dev branch.

Changelog

0.3.0

  • Add support for lolcate-rs as a cached_list provider
  • Add an option to restrict the search to some directories
  • Add fallback command so that :Telescope repo does not error
  • Fixes:
    • keep Telescope prompt in insert mode (nvim 0.7+)
    • the search_dirs argument is not mandatory
  • Dev: add tests, CI, formatting with stylua
  • Documentation: update with new features, installation instructions, code formatting reference and other fixes

0.2.0

  • Add support for checkhealth
  • Add picker that builds the list of repositories from locate, thus taking profit of a system-wide index.
  • Add mappings leading to various actions
  • Preview non-markdown Readme file

0.1.0

  • Basic feature, generate a dynamic project list with fd
  • Falls back to file listing if we are not in a git repository

Footnotes

  1. SCM: Source-Control Management

  2. See also Stability

More Repositories

1

rusqlite_migration

↕️ Simple database schema migration library for rusqlite, written with performance in mind.
Rust
68
star
2

readme-in-static-site

💎 Transform and insert your GitHub readme in your static site.
Awk
35
star
3

bepo.nvim

⌨️ Mappings for the bepo keyboard layout in Lua, inspired by https://github.com/michamos/vim-bepo
Fennel
16
star
4

gohugo-asciinema

⏯️ Insert the Asciinema Player in your Hugo site with ease.
CSS
16
star
5

gohugo-shorturl

🔗 Hugo module to create shorturls (so your shorturl like my.site/short can redirect to asitewithalong.name/andanevenlongerpath)
HTML
8
star
6

sesters

💱 Fast, offline currency converter 💴 💷 💶 💵
Rust
5
star
7

minimal-format.nvim

Minimal, smart formatting using native neovim capabilities.
Lua
4
star
8

oclaunch

🚀 Lauch various command, once, when opening a terminal
OCaml
3
star
9

miniflux-gemini

Expose your Miniflux instance to Gemini
Go
3
star
10

trie.fennel

Fennel and Lua library for Trie data structure
Fennel
2
star
11

planckez-cli

**Work in progress** Trying to create a heatmap command-line daemon
Rust
2
star
12

telescope-repo.nvim-macos

Test https://cj.rs/telescope-repo.nvim on macos
Lua
2
star
13

cljoly

2
star
14

ledgerdb

Fork of https://git.sr.ht/~adchari/ledgerdb
Rust
2
star
15

telegram-tee

💬 Simple cli tool to create telegram bot behaving like tee
Go
2
star
16

lightweight-container-proxy

🔒 Lightweight Firefox addon providing SOCKS5 proxy per container
JavaScript
2
star
17

openpomodoro-hooks

🪝 Hooks I use with open-pomodoro cli
Shell
2
star
18

.github

Common community files
2
star
19

onedark-fast.nvim

Port of onedark to fennel, so that we generate fast Lua code.
Lua
1
star
20

data

📊 Data sets to populate some parts of my website (mostly https://cj.rs/open-source/).
Shell
1
star
21

misc

Misc. files for various webapp
1
star
22

telecomnancy-flashcard

Flashcard app, created during a coding week with my team. Group of 4 people. [School Project]
Java
1
star
23

ledger.ctags

Ctags file for ledger-cli
Shell
1
star
24

telecomnancy-rsfind

🕵️ Find-like command, using only low-level system call and with additional features [School Project]
C
1
star
25

telecomnancy-Cproject

Film recommendation with graphical interface, written in C [School Project]
C
1
star
26

url_dump

POST urls, GET atom feed
1
star
27

pomodoro

🍅 Paper-like, light, pomodoro timer
Scheme
1
star
28

fast-marks.nvim

[Given up] A fast and improved user-experience for viewing and interacting with Vim marks.
Lua
1
star
29

telecomnancy-telegram-bot-learn-english

🤖 Simple Telegram bot to learn English. Group of 2 people. [School Project]
Python
1
star
30

readme-as-site

Achived for now, we have https://cj.rs/readme-in-static-site/. May be revived to extend the above script and to apply it to a bunch of .md files.
CSS
1
star
31

pure-sixel

Pure Rust sixel encoder
Rust
1
star
32

mosh-srv

[Given up for now] Wrapper around mosh (and eventually ssh) to use SRV records
Go
1
star
33

telecomnancy-web

Github Education-like dashboard, for Gitlab, written in Python, CSS/JS/HTML. Developed in a group of 4. [School Project]
Python
1
star
34

hmrc2ledger

Put HMRC rates in a ledger database
Awk
1
star
35

telecomnancy-twitter-like

🦜 Twitter-like service, with a client and a server. Use network system calls and SQLite in C while preventing SQL injections. Group of two people (me, @Laur2do) [School Project]
C
1
star
36

go-sqlite-migration

Demo of golang Migrations with SQLite, using user_version
Go
1
star
37

ledger-lint-duplicate

Small go utility to find transactions that may be duplicated in a ledger file.
Go
1
star
38

copyright-header

Check all copyright headers in your project. For use with any licenses: GPL, MPL, Apache, MIT
Awk
1
star
39

pico-heater

Heating control with a raspberry pi pico
Python
1
star
40

hardline-parts

Custom parts for https://github.com/ojroques/nvim-hardline
1
star