org-git-link allows linking to specific (git) versions of a file.
Often one wants to link to a specific version of a reference document which may change in time. Thorsten Wagner described an important use case in his mailing list entry (https://firstname.lastname@example.org), namely linking to results in a lab book. Quote:
#+BEGIN_QUOTE [...] Please think about the following situation: I have something like "... In the [graph] of the last results, a huge peak is observable due to measurement problems for the following set-up parameters ...." in my org-file and then several month later in a stupid act I overwrite this file by some very similar but different results, e.g. because I was not longer aware of the link and thought there is no need to keep this old graph with the ugly peak and replace it by something "better". Now the link still depicts to a graph (lets say without or smaller peak) and back in org-mode I might reread my entries check what I did several months ago... and I will be very confused since the graph and the written text have some quirks (refer to a peak where no peak is depict in the graph and refers to wrong measurement parameters) my boss ask me what sort of mess I did, which I can not explain. He claims its the fault of all this "linux-hacker- emacs-org-mode-work-only-on-text-files"-stuff blaims me to dead and force me switching back to use Outlook, MS Office and MS Windows for the rest of my life..... wooohhh that would be a sad story !!!! #+END_QUOTE
What a sad story indeed. Collaborative editing is another case where linking of (e.g.) todo items to specific versions or to files in different branches comes in handy.
org-git-link.el defines two new link types. The
type is meant to be used in the typical scenario and mimics the
file link syntax as closely as possible. The
type exists mostly for debugging reasons, but also allows e.g.
linking to files in a bare git repository for the experts. I
will first show an example usage for both kinds of links before
the syntax is defined more formally.
In all these examples, the linked files do not even have to exist in the working repository, i.e. the links continue to work even after the files have been deleted.
#+BEGIN_EXAMPLE git:/path/to/file::searchstring #+END_EXAMPLE This form is the familiar from normal org file links including search options Search options. However, its use is restricted to files in a working directory and does not handle bare repositories on purpose (see the bare form for that).
The search string references a commit (a tree-ish in Git terminology). The two most useful types of search strings are
For other ways to specify commits see the git documentation referenced in the bare git section.
From the (not necessarily existing) file path first the corresponding git directory is extracted. This is done in the following way: Starting with the directory of the linken file, it is checked whether
If not, the procedure is iterated with the parent directory. The link path (which can be given as a local link) is thus separated into an absolute path GIT_DIR to the git directory (without .git) and a relative path RELPATH to the file. Git is now called as
git --no-pager --git-dir=GIT_DIR/.git show SEARCHSTRING:RELPATH
#+BEGIN_EXAMPLE gitbare:GIT_DIR::OBJECT #+END_EXAMPLE This is the more bare metal version, which gives the user most control. It directly translates to the git command
git --no-pager --git-dir=GIT_DIR show OBJECT
Using this version one can also view files from a bare git
repository. For detailed information on how to specify an
object, see the man page of
SPECIFYING REVISIONS). A specific blob (file) can be
specified by a suffix clolon (:) followed by a path.
Following any of the git links creates a direcory named
temporary-file-directory (if it
does not exist), where SHA is the hash of the linked file
(blob). The file contents is saved within this directory under
the name used in the link. This ensures that each file is only
checked out once, even when they are referenced by different
search strings (e.g. once by branch name and once by tag). The
file is supsequently opened using
org-open-file, which does
the right thing for non-text files as well.
As an org mode is a simple text file, a git link can of course be inserted directly as a string. For your convenience two functions creating links automatically have been defined: