Open source developers often have to jump between projects, either to read code, or to craft patches. My Repo Pins reduces the friction so that it becomes trivial to do so.
The idea of the plugin is based on this idea; if the repository URLs can be translated to a filesystem location, the local disk can be used like a cache. My Repo Pins lazily clones the repo to the filesystem location if needed, and then jumps into the project in one single command. You don't have to remember where you put the project on the local filesystem because it's always using the same location. Something like this:
The minimal configuration consists in setting the directory in which you want to clone all your git repositories via the `my-repo-pins-code-root` variable.
Let's say you'd like to store all your git repositories in the `~/code-root` directory. You'll want to add the following snippet in your Emacs configuration file:
You can then call the `M-x my-repo-pins` command to open a project living in your `~/code-root` directory **or** clone a new project in your code root.
Binding this command to a global key binding might make things a bit more convenient. I personally like to bind it to `M-h`. You can add the following snippet to your Emacs configuration to set up this key binding:
For instance, after checking out https://git.savannah.gnu.org/git/emacs/org-mode.git, the source code will live in the my-repo-pins-code-root/git.savannah.gnu.org/git/emacs/org-mode/ local directory
Alist in the form of `("FORGE NAME" . FETCH-FUNCTION)` where `FETCH-FUNCTION` is a function in charge of retrieving a potential remote clone URL. More about this function in the [Fetchers](#fetchers) section.
The my-repo-pins-open-function variable can be customized if you would prefer to land in some other program than Dired. Good candidates might be the builtin 'vc-dir or 'magit-status if you use the popular Magit package:
When a repository cannot be found in the code root directory, `my-repo-pins` will try to download it from different forges. By default, it'll try to find it on github.com, gitlab.com, git.sr.ht, and codeberg.org.
-`instance-url`: your instance [FQDN](https://fr.wikipedia.org/wiki/Fully_qualified_domain_name). For instance: `gitlab.gnome.org`, `git.alternativebit.fr`, …
-`user-name`: the user name for which we want to clone the repository.
-`repo-name`: name of the repository we want to clone.
-`callback`: function `my-repo-pins` will use to clone the repository once we retrieved the various clone URLs. The callback takes an alist as parameter. The alist being of the form of : `((ssh . SSH-CHECKOUT-URL) (https . HTTPS-CHECKOUT-URL))`.
You can re-use these functions by instantiating them for a specific forge, then by appending this instantiation to the `my-repo-pins-forge-fetchers` variable in your Emacs configuration.
Let's say you want to retrieve repositories from the Gnome Gitlab instance living at `gitlab.gnome.org`. You'll have to add the following snippet to your Emacs configuration:
You may also want to support a forge for which `my-repo-pins` currently does not provide any generic fetcher. In that case, you'll have to write a function in the form of:
This function will return either `nil` in case the query couldn't be found on the remote forge. An alist containing the SSH and HTTPS clone URLs in the form of:
- This plugin is heavily inspired by [**Zimbatm's h**](https://github.com/zimbatm/h). Thanks a lot for this amazing tool, it made my life easier for years!
- Thanks a lot to Wiwi who found the **terrible** pun we used to name this project.