Git/VCS library

[wbthomason]

What?
A Lua library for working with git/other VCS information in Neovim. Kind of an equivalent to https://github.com/tpope/vim-fugitive or https://github.com/mhinz/vim-signify

Why?
The existing VCS solutions for Vim/Neovim are written in Vimscript and are fairly complicated and expensive to load. Additionally, interfacing with VCS is a common problem for some classes of plugin - plugin managers, statuslines, etc. A Lua library, using vim.loop to asynchronously run VCS software and handling things like branch detection, change counting while editing, cloning, displaying changes, making commits, and pushing/pulling (among other functionality) would reduce effort duplication and increase performance.

Potential existing implementations:
Some rudimentary branch detection/change tracking functionality is implemented in https://github.com/wbthomason/dotfiles/blob/linux/neovim/.config/nvim/lua/git.lua. Vimscript plugins like fugitive and signify can be used as references for some of the tricker bits of working with git.

Potential pitfalls:
fugitive and the like are complex plugins to replicate.

[smolck]

@wbthomason Why is this marked as in-progress? (More specifically, are you working on https://github.com/wbthomason/dotfiles/blob/linux/neovim/.config/nvim/lua/git.lua to eventually make it a library, or . . . ?)

[wbthomason]

It was marked in progress because of https://github.com/wbthomason/dotfiles/blob/linux/neovim/.config/nvim/lua/git.lua; maybe I should move it back to the "idea" stage because I haven't split out that file into a separate plugin yet.

I'd like to keep working on that module and make it a library; it's stable for what it provides, but it provides relatively little. Haven't had time for it lately, though.

@smolck: Do you think it would be better to move this card back to "Ideas"?

[smolck]

I'd like to keep working on that module and make it a library; it's stable for what it provides, but it provides relatively little. Haven't had time for it lately, though.

I'm happy to help out with expanding upon it as I'm able, but I'd probably need some specific direction first as to where you'd like to go with it. I'm also curious if having a UI for the library is something you'd want to add as part of this wish? My thought is we could have the library be something that can be used by itself (i.e. requireed), and then maybe have the UI as part of a separate plugin? Or maybe in a separate module of the same plugin? I'm not sure exactly how that'd be structured.

@smolck: Do you think it would be better to move this card back to "Ideas"?

Yes, I think so; maybe there should be some more specific criteria for what constitutes an "idea," an "in-progress" plugin, and a "done" plugin (which we've basically already decided in #2). I do think that "in-progress" implies that the plugin is actively being worked on in it's own repository though; what do you think?

Also, do you think there should be a standard way for the plugins to be structured, i.e. neovim-plugin, in order for them to qualify as "in-progress" or "done"? I think if we are going to have a standard structure for Lua plugins, this might be a good place to start using it. Thoughts?

[wbthomason]

I'm happy to help out with expanding upon it as I'm able, but I'd probably need some specific direction first as to where you'd like to go with it. I'm also curious if having a UI for the library is something you'd want to add as part of this wish? My thought is we could have the library be something that can be used by itself (i.e. requireed), and then maybe have the UI as part of a separate plugin? Or maybe in a separate module of the same plugin? I'm not sure exactly how that'd be structured.

I suppose I should split it out into its own repo, and then we/anyone who's interested in working on it can discuss this there. In short: I like the idea of making it a library with a separate or optional UI component (something like I did for lsp-status, with the optional "default" statusline component).

Yes, I think so; maybe there should be some more specific criteria for what constitutes an "idea," an "in-progress" plugin, and a "done" plugin (which we've basically already decided in #2). I do think that "in-progress" implies that the plugin is actively being worked on in it's own repository though; what do you think?

I buy that argument; I'll move the card until I get around to separating out a new repo. Would you be interested in making a PR on this repo to add more formal specifications of what constitutes an "idea", "in-progress" plugin, etc.? I think there's enough interest from you and @clason that we should think about how these should be defined.

Also, do you think there should be a standard way for the plugins to be structured, i.e. neovim-plugin, in order for them to qualify as "in-progress" or "done"? I think if we are going to have a standard structure for Lua plugins, this might be a good place to start using it. Thoughts?

Personally, I don't favor requiring all implementers of ideas to use a fixed structure. I think neovim-plugin could develop into something useful, and developers should be encouraged to use a standard structure, but I prefer leaving the choice open. I could be convinced otherwise, though, and if neovim-plugin is more widely adapted as a standard my thinking on this might change.

[clason]

I think there's enough interest from you and @clason that we should think about how these should be defined.

I don't think a detailed set of criteria is required; just some rule-of-thumb so it's not completely arbitrary. Having a dedicated repo with some code in it is fine for "in progress".

I suppose I should split it out into its own repo, and then we/anyone who's interested in working on it can discuss this there. In short: I like the idea of making it a library with a separate or optional UI component (something like I did for lsp-status, with the optional "default" statusline component).

I think it makes sense to separate this into

1. a basic "interacting with git" layer
2. a set of functions doing "vim-stuff" like statusline components or signs
3. a fugitive-style git UI

My personal short-term interest would be in 2. rather than 3. (As well as maybe adding mercurial support.)

Personally, I don't favor requiring all implementers of ideas to use a fixed structure.

I don't think any requirements (besides being written in lua and doing something useful) should be made; this would send the wrong sign. A version of https://github.com/nanotee/nvim-lua-guide for "Writing lua plugins in neovim" that promotes neovim-plugin may be useful, though.

[smolck]

Would you be interested in making a PR on this repo to add more formal specifications of what constitutes an "idea", "in-progress" plugin, etc.?

Sure! I agree with @clason about having "just some rule-of-thumb so it's not completely arbitrary," so maybe a PR updating the README to list some basic distinctions between "idea," "in progress," and "done" is fine? We can of course decide on the exact wording/distinctions in the PR, but I think we're already decided for the most part, so it should be a straightforward update.

I think it makes sense to separate this into

1. a basic "interacting with git" layer
2. a set of functions doing "vim-stuff" like statusline components or signs
3. a fugitive-style git UI

My personal short-term interest would be in 2. rather than 3. (As well as maybe adding mercurial support.)

I agree, that sounds good! I wonder if 3 would make sense as a separate plugin that uses the library? Because if we're going for something like a magit equivalent (but better, of course :P), then it might belong as a separate plugin. That way if someone wants to use only the library they can pull that in by itself.

Personally, I don't favor requiring all implementers of ideas to use a fixed structure.

I don't think any requirements (besides being written in lua and doing something useful) should be made; this would send the wrong sign. A version of https://github.com/nanotee/nvim-lua-guide for "Writing lua plugins in neovim" that promotes neovim-plugin may be useful, though.

Good points. Maybe such a guide could be part of this repository (maybe in the Wiki)? Just a thought; I'm not sure if that's better than having it in a separate repo, or if that's outside the scope of this project.

[clason]

I wonder if 3 would make sense as a separate plugin that uses the library? Because if we're going for something like a magit equivalent (but better, of course :P), then it might belong as a separate plugin. That way if someone wants to use only the library they can pull that in by itself.

Arguably, 2 (and certainly 1) could be part of a standard lib, while 3 is definitely a plugin. (It's always possible to factor things out later, though, so that doesn't have to be fixed now.)

[polarmutex]

I am very interested on working on this effort. I am planning to get a project started to start playing with ideas.

[wbthomason]

@bryall Sounds good! That served as the final kick in the pants I needed to extract my own current WIP toward this from my dotfiles to its own plugin: https://github.com/wbthomason/nvim-vcs.lua

Feel free to contribute to that repo or start your own; whatever you prefer.

[bfredl]

are some of you guys aware/planning to use https://libgit2.org/luagit2/modules/Commit.html ?
Neovim 0.5 wants to fully support bindary deps via luarocks, so doing a luarocks install lua-git2-scm should be fine.

[wbthomason]

@bfredl I wasn't aware core was planning to integrate Luarocks support - could you point me to a PR? That impacts this project idea, but also some of the work on packer (and would generally be great to have).

[bfredl]

Ping @tjdevries once his talk is over (20 mins ish) :]

[bfredl]

@wbthomason we might not be able to fully "commit" to a working solution inside nvim 0.5 release. However, I think packer.nvim could work nicely as a "sandbox" where we try to work out binary (luarocks) and plugin dependencies (i e plugin A depend on B), and maybe get something into neovim core in 0.6 or later. Does this sound alright with you? I might be able to help prototype libgit2 stuff myself, sometime soon.

[polarmutex]

@bfredl i saw a PR for updating luagit2, do you need any help? I started looking at it when i saw it

[bfredl]

@bryall I have just had other as stuff to do :] but feel free to send a PR on top of my PR if you wanna accelerate the process.

[wbthomason]

@bfredl Yes, that plan sounds good (I really need to make time to finish the packer Luarocks PR soon...)

I'll note that packer already handles (manually specified) plugin dependencies; see the requires keyword if you haven't already.

[lewis6991]

Just going to mention/plug I've been working on a lua plugin (gitsigns.nvim) as a drop in replacement for vim-gitgutter or coc-git.

Still very WIP but pretty usable for my personal needs.

[gennaro-tedesco]

I too would offer my help for development: is this being considered any time soon, practically, so that one could start drafting requirements and proof of concepts? Or is this being already developed here?

[cd-a]

@gennaro-tedesco I'd rather say it's being developed here: https://github.com/TimUntersberger/neogit

See wbthomason/nvim-vcs.lua#1

[clason]

To recap the current state:

1. a base git library (e.g., in https://github.com/nvim-lua/plenary.nvim) is still missing (basically, waiting on https://github.com/libgit2/luagit2 to make a release);
2. a very good signify-style plugin for signs and statusline components (and interacting with hunks) exists: https://github.com/lewis6991/gitsigns.nvim
3. a fugitive-style git frontend is still being developed but pretty usable: https://github.com/TimUntersberger/neogit (takes its inspiration from magit rather than fugitive so the UX is different, but the functionality is the same).

[matu3ba]

@clason luagit2 needs alot more polishing to be usable. Just look at the issues mentioning libgit2 release 0.18 and the build crash issue. Since libgit2 is v1.0 since last May stuff does not break in the foreseeable future, so now would be the ideal time for you to push things. ;-)

[bfredl]

some work towards 1.0 has been done in luagit2, though I did not get the existing makefiles to cooperate without hacks.