My Emacs package of the week: orgit

2022-01-21

859 words, ~6min reading time

As you may now I joined the 100 Days To Offload challenge and therefore need some content. Since it seems that I always write about stuff that is more or less connected with Emacs anyway I though I could start a series called "My Emacs package of the week" where I present some package I stumbled upon recently or I used for quite some time but is interesting enough to show. I intend to do this weekly (at least during the challenge) but I cannot promise that I find a package every week that I want to present.

However, this weeks package is orgit by Jonas Bernoulli (the guy that also maintains Magit, the one and only Git interface). What does it? It defines Org link types for linking to Magit buffers from Org mode.

So, why is it may favorite package of the week? When I develop software I like to keep track of the tasks I would like to achieve (of course using Org) and I found out that I also really like to write down my thoughts on tasks that come to me over time. So when I finish a chore the Org entry sometimes resemble more a story than just a todo. Since it is still software development "behind"" the scenes, Git plays an important role. In the past when I pasted commit SHAs I usually linked to the corresponding commit in the remote but I would prefer it, if takes me to my local clone instead. So I searched quickly earlier this week and was quite surprised and happy that the first result was from the Magit GitHub organization.

Since the last days were a little bit busy I first had no time to try the package and later decided that I could combined this with a blog post. So lets start by loading it with use-package (I have Melpa configured but it is also available on NonGNU ELPA).

(use-package orgit
  :after (magit org))

The package itself provides only one command which may be interesting further down the road: orgit-store-link. Reading the documentation it acts the same as the org-store-link function but not storing a link to one commit but to all selected commits. For now I only want to link to one commit. Since the file I'm writing this very blog post into is actually stored in a Git repository this is obviously the best example to start. After opening my Magit status buffer with C-x g (that is holding the control key while pressing x, letting go of both and pressing just the g letter).I went to the "recent commits" section, open the commit of my previous post and got the link to it using org-store-link (I have it bound to C-c l but not sure if I or Org did this). Afterwards I can insert the link using org-insert-link (C-c C-l) and here it is:

[[orgit-rev:~/projects/mmk2410.org/::e1b5ee5496fe7147c77985ac5f49e8bb7f4d4725][~/projects/mmk2410.org/ (magit-rev e1b5ee5)]]

Opening this link using org-open-at-point (C-c C-o) brought me directly to the Magit buffer for the revision. For just linking to the Magit status buffer of my project I can execute the org-store-link command right after opening it.

[[orgit:~/projects/mmk2410.org/][~/projects/mmk2410.org/ (magit-status)]]

And visiting it works just the same!

But there is currently a problem. When exporting an Org buffer e.g. to Markdown to upload it to a team wiki or something else, Org checks whether the links are resolvable and fails for the orgit ones. Makes sense since nobody else can open my Magit buffer from a Wiki (at least I hope so!). But this is where orgit gets really good: it has built-in support for exporting these links and this is also enabled by default. There is just one catch why it does not work for me. orgit uses by default the remote named origin (this can be customized by setting orgit-remote) and creates the real HTTP links using the predefined forges and their base URLs. Since I use my own self-hosted Gitea instance it is clear that Orgit dos not know a base URL for it. So lets adjust the orgit-export-alist variable that stores this configurations by adding a definition for my Gitea instance.

(add-to-list 'orgit-export-alist
             '("git.mmk2410.org[:/]\\(.+?\\)\\(?:\\.git\\)?$" ;; the regex to match the remote
               "https://git.mmk2410.org/%n" ;; The link to the status
               "https://git.mmk2410.org/%n/commits/commit/%r" ;; The link to the log.
               "https://git.mmk2410.org/%n/commit/%r")) ;; The link to the revision

As written in the documentation for orgit-export-alist it is also possible to set these values using the git config command with the keys orgit.status, orgit.log and orgit.commit. Thereby only the %r (the revision) must appear in the string of the last two keys. The %n in the code above will get expanded to the path of the project. Using this configuration the exporting works and I can now also link here to my projects overview page and the commit of my last blog post (Update 2021-02-03: Well, at least in theory and also locally. But since I'm now probably building my block using a GitLab CI pipeline the links to not work since Orgit cannot find the directory in the link location. Therefore I needed to remove the links.).

That's it! I sure will integrate this package into my workflow and Emacs configuration and I hope you enjoyed this brief presentation.

P.S.: If you 're already a heavy user of Magit then I would like you to consider sponsoring Jonas.

Day 5 of the #100DaysToOffload challenge.