- jumping into function definitions when navigating code bases is a
fairly common operation with wide support
- eg
xref-find-definition, plugged into eglot, combines the power of an lsp backend with emacs features to make this simple
- eg
- however, there isn’t an intuitive, customizable mechanism for navigating backwards, or more generally, with ring semantics. namely, it’s hard to know where i’ve been, after jumping from function definition to function definition, delving more deeply into the calls
- in the absence of this package, the extant ways to do this seem to
be:
xref-go-backandxref-go-forward: the navigation semantics aren’t that intuitive (stack-based) and, more importantly, users cannot add custom entriesmark-ring: does not seem desirable, as it pollutes intent- bookmarks: ditto
- dogears or gumshoe: both of these packages are great, and this
package is largely inspired by the two of these. however, i,
personally, have no interest in using either time or distance as a
signal for tracking positions. i am principally interested in:
- support for position tracking in live and killed buffers
- support for relative position tracking using marker semantics, so changes before and after a tracked position do not inadvertently move it
- support for persisting the list of tracked positions between emacs sessions, which raw markers do not allow
- well-defined, ring-based navigation
- allowing arbitrary functions to track the before and after positions around the call
- that last bit is most useful to my workflow, as when i’m trying to understand a bit of code, i usually have to move projects into some library definition - the semantics of which i am usually unfamiliar, and i waste time trying to figure out how to walk backwards
- work with tramp
| name | description |
|---|---|
trail-ring | the list of trail-marks, stored in a ring buffer. can be persisted via savehist, but needs to serialize with trail-mode |
trail-ring-max | the number of trail-marks to track in trail-ring |
trail-mark-around-functions | the list of functions, which, upon invocation, mark along the trail before and after execution |
| name | description |
|---|---|
trail-mode | enables usage of trail |
trail-mark | marks along the trail, ie tracks the position, of point in the current buffer. trail-marks in killed buffers, when jumped to, will open the pursuant file. if point is at a known trail-mark, the existing trail-mark will be moved to the head of the list |
trail-list | displays the list of trail-marks in a separate buffer. trail-marks can be jumped to with “<RET>”, deleted with “k”, expanded with “e”, and searched with full names using completing-read with “j”. “r” jumps to the line with the most recently marked or jumped-to position |
trail-find-and-jump-next | jumps to the next trail-mark given the trail-mark at point. otherwise, do nothing |
trail-find-and-jump-previous | if point is at a known trail-mark, jump to the previous trail-mark. otherwise, jump to the most recently marked or jumped-to position |
(use-package trail
;; if using a persistence/restoration mechanism, the restoration of
;; trail-ring must happen before trail-mode is enabled
:after savehist
:custom
(trail-mark-around-functions '(xref-find-definitions xref-find-references))
(trail-ring-max 100)
:init
(trail-mode)
:bind
("C-M-=" . trail-mark)
("C-M-'" . trail-list)
("C-M-[" . trail-find-and-jump-previous)
("C-M-]" . trail-find-and-jump-next))
(use-package savehist
:init
(savehist-mode)
(setq savehist-additional-variables
'(trail-ring)))