cole-brown/groot

Support for Org links to git repo & git-rooted file path.

Why?

Ever wanted a link to a repository that’s rooted in the repository? A nice concise way to say, “Whereever my foo repository is, link to ‘src/bar/baz.qux’”?

Ever wanted a quick way to tell a teammate about a repo and file, in a way that makes more sense than “~/random/path/to/my/repositories/foo/src/bar/baz.qux”?

Git uses “:/” in the pathspec to mean “root of the working tree” (aka “root of the repo”), so a pathspec of :/src/bar/baz.qux would be to said file, as long as we’re in the foo repository.

groot just appends the repository’s name in front of the pathspec in order to know where to go even when outside the repository: foo:/src/bar/baz.qux

It’s a bit nicer than: /home/username/random/path/to/my/repositories/foo/src/bar/baz.qux

Quick Start

The simplest way is probably use-package.

(use-package groot)

If you have all the repos you want groot to care about in magit-repository-directories, that’s all you need.

Otherwise, you need to tell groot where your repos are so it can make and follow links. groot has two helpful functions for this, groot-repositories-append and groot-path-repositories.

(use-package groot
  :config
  (groot-repositories-append
   ;; Add repos one-by-one...
   "~/path/to/specific/repo"
   ;; ...or scan each direct child folder of a path and all all repos found...
   (groot-path-repositories "~/.config")
   ;; ...or give your repo a nickname.
   ;; Maybe the repo is named "alias" on the filesystem, but we want to refer to
   ;; it as "nickname" for whatever reason.
   (cons "nickname" . "~/path/to/repo/alias")))

And that’s all folks. Evaluate your use-package and then groot should start working when you use org-store-link, org-insert-link, org-open-at-point, etc.

Link to known Git repo files from Org documents

This package defines the groot Org link type, which can be used to link to files in Git repositories. Use the command org-store-link while such a buffer is current to store a link. Later you can insert it into an Org buffer using the command org-insert-link.

How Groot Finds Repositories

Four variables control what repositories groot knows about, in this order of priority:

• groot package:
  • groot-repositories
• autogit package:
  • autogit:repos:path/commit
  • autogit:repos:path/watch
• magit package:
  • magit-repository-directories

If groot can find the path in one of those variables, it can create & follow groot: links.

The Git repository must be known in order to create or follow a link.

groot looks for “known repositories” in these variables, in this order:

1. groot-repositories
2. autogit:repos:path/commit
3. autogit:repos:path/watch
4. magit-repository-directories

Settings

groot-repositories

Alist of Git repositories.

Each element has the form (NAME . PATH)

• NAME: string - repository’s name (usually the same as the repo dir name)
• PATH: string - absolute path to the repo’s root directory

NOTE: `groot-path-repositories’ is a helpful function that will find all Git repos directly under a dir. However, it cannot be used in `use-package’ `:custom’ section, so you’d have to wait for the `:config’:

(use-package groot
  ...
  :config
  ;; `setq' and `customize-set-variable' both work. So these are equivalent:
  (customize-set-variable 'groot-repositories
                          (list (groot-path-repositories \"~/.config\")
                                (groot-path-repositories \"~/repos\")))
  (setq 'groot-repositories
        (list (groot-path-repositories \"~/.config\")
              (groot-path-repositories \"~/repos\")))

  ;; Or use `groot-repositories-append' helper:
  (groot-repositories-append (groot-path-repositories \"~/.config\")
                             (groot-path-repositories \"~/repos\")
                             "~/path/to/repo-name"
                             '("alias" . "~/path/actual-repo-name")))

groot-ignore-major-modes

List of major mode symbols we should not take responsibility for org links. This allows other org link types to make the link instead.

NOTE: `major-mode’ is compared using `derived-mode-p’, so these and all derived modes are ignored.

(use-package groot
  ...
  :custom
  (groot-ignore-major-modes '(org-mode diff-mode)))

groot-ignore-predicates

List of predicates for whether to not take responsibility an org link. This allows other org link types to make the link instead.

Predicates take a buffer-object and return non-nil for "ignore this buffer".

See `groot-link–store?’ for default ignores.

(use-package groot
  ...
  :custom
  (groot-ignore-predicates '(my-ignore-function)))

Format

groot link type takes these forms, similar to the file link type:

groot:repo:/relative/path/to/file.el
groot:repo:/relative/path/to/file.el::location-in-file

Export

Currently nothing special happens to groot links when the org file is exported.

Having something rather than nothing happen is a TODO.