[Feature Discussion] Install a particular commit

[cljoly]

Note

This is similar to #114, but the reasoning for the feature is different, so I thought it was best to create a separate issue. Also, I think it’s doable now.

Context

A nvim plugin can basically do anything on a computer. So when I install a plugin that I don’t have any particular reason to trust, I often read the code for the latest commit on master, to check that nothing fishy is going on. However, just because a particular version seems harmless does not mean that any future version will not introduce malicious behaviour. So I would like to be able to pin the plugin to the particular commit I reviewed, until I might decide at a later point to review again and update.

I am aware that I can use pin = true on individual packages and then PaqUpdate won’t update the package. But that pins the package to the reviewed version only for existing installs. A brand new neovim (on a new virtual machine for instance) install will pull the latest version of all packages again, pulling in potentially unreviewed commits. Pointing to tags could help, but they can be mutated (e.g. if the repo is taken over) and I may want to use a commit that’s not tagged.

A similar feature was discussed in #114, but I think that the situation has changed. Now git is able to do a shallow clone from a particular commit, using the --revision argument introduced in version 2.49.

Possible implementation

I have looked into git clone --revision and it can be used like so:

git clone --depth=1 --recurse-submodules --shallow-submodules --no-single-branch --revision '3662c91fc7d63dfc14088bbf17e5f495254a3ec3' https://github.com/savq/paq-nvim.git

The resulting repository holds history only for that one commit, like a normal shallow clone.

Unfortunately, pulling inside that shallow clone will change the current commit, so additional logic is needed to reset back to the desired revision.

One final drawback is that git version 2.49 is not available on Debian Trixie nor Ubuntu 25.04 (but it looks like Ubuntu 25.10 will have 2.51). So paq-nvim would need to have additional logic to handle an old git, for instance, erroring if the version is not supported.

I’ve started a prototype of that feature to get a sense of how this change would integrate in the codebase. It could be used as a basis of a PR, should you decide to consider one.