bookmark-gt extends the built-in bookmark.el and is fully compatible with it. When enabled, the standard bookmark keys run the corresponding
bookmark-gt commands. Its bookmarks are ordinary bookmark.el records, thus a bookmark file
written by bookmark-gt can still be read by the built-in bookmark package.
bookmark-gt is inspired by bookmark+.
bookmark-gt’s main features are:
- tags, including default tags computed from the location being bookmarked;
- several bookmarks with the same name, distinguished by their destination;
- a bookmark list buffer for searching, filtering and updating many bookmarks at once;
- bookmarks that follow their file when it is renamed inside Emacs;
- a jump reader that works with marginalia, vertico, consult and orderless;
- temporary bookmarks, which are never saved to disk;
- auto-update bookmarks, which keep track of where you are in a long document;
- bookmark types for URLs, Dired buffers, functions, keyboard macros and sequences of bookmarks.
A short demo: https://youtu.be/hitAyO8ArYM
With use-package and a local checkout:
(use-package bookmark-gt
:straight nil
:load-path "~/.emacs.d/modules/bookmark-gt"
:bind (("C-x r u" . bookmark-gt-create-url) ; bookmark a URL
("C-x r U" . bookmark-gt-update)) ; move a bookmark to point
:config
(bookmark-gt-mode 1))bookmark-gt requires Emacs 30.1 or later. While bookmark-gt-mode
is on, the built-in bookmark keys are remapped to run the corresponding
bookmark-gt functions:
| Key | Built-in | Runs |
|---|---|---|
C-x r m | bookmark-set | bookmark-gt-create |
C-x r b | bookmark-jump | bookmark-gt-jump |
C-x r l | bookmark-bmenu-list | bookmark-gt-list |
M-x | bookmark-delete | bookmark-gt-delete |
M-x | bookmark-rename | bookmark-gt-rename |
Turning the mode off restores the original key bindings.
The following packages are optional; bookmark-gt uses them when they are installed and works without them:
marginaliaadds tags, type and location to each candidate in the jump reader;orderlessenables the@type,+groupand;tagnarrowing particles in the jump reader;browser-gtis required only bybookmark-gt-browser-tabs-mode.
M-x bookmark-gt-version shows the installed version followed by
the Emacs version, which is the line to include in a bug report.
With a prefix argument it inserts that text at point instead.
From Lisp it returns the version string, which is also the value
of the variable bookmark-gt-version.
bookmark-gt-mode is a global minor mode that turns on every
bookmark-gt feature described in this manual. When bookmark-gt-mode is off,
the built-in
bookmark.el behaves as it does without bookmark-gt.
While bookmark-gt-mode is on, the following features are available:
bookmark-gt-createcreates bookmarks. It prompts for the name with a suggestion derived from the location being bookmarked (not from the last bookmark you jumped to), already inserted as editable text, soRETaccepts it andC-a C-kreplaces it. It then prompts for tags, applies the same-name policy, and uses bookmark-gt’s Dired handler when the current buffer is a Dired buffer. Bookmarks whose names matchbookmark-gt-auto-temp-names, such asorg-capture-last-stored, are made temporary when they are stored.- Every jump increments the bookmark’s
visitscount and sets itslast-visitedtime. This information is used to enable a most-recently-used ordering of the bookmarks. bookmark-gt-jumpreplacesbookmark-jump. It lists the most recently used bookmarks first, shows marginalia annotations and accepts orderless narrowing particles (such as;TAG,@TYPEand+GROUP) when those packages are loaded, and lets you filter by tag while it is reading (M-tadds a tag filter,M-dremoves the last one,M-Dremoves all of them).- You can specify how a file bookmark is opened.
A file bookmark whose
filenamematches a regexp inbookmark-gt-file-type-handlersis opened by the function associated with that regexp instead of byfind-file. - When a file is renamed with
rename-file(which Dired’sRuses), every bookmark pointing at the old name is changed to point at the new one. - Temporary bookmarks exist only for the current Emacs session. They appear in the list buffer and the jump reader like any other bookmark, but they are never written to the bookmark file, and creating them never causes the file to be saved. Making a temporary bookmark permanent, or a permanent one temporary, is a change to the bookmark file like any other.
Turning the mode off removes every advice and hook it installed. The three optional modes below are turned on and off separately.
The following global minor modes are off by default.
A bookmark with the auto-update property is moved to the current
position of the buffer that visits its file, which is useful for
keeping your place in a book, a long document or a PDF. The
position is updated when Emacs has been idle for
bookmark-gt-auto-update-interval seconds (default 60), when the
buffer is killed, when the window configuration changes, and when
the list buffer is opened or reverted.
To set or clear the property, press ^ in the list buffer (it
acts on the marked rows, or on the row at point when none is
marked), or use M-x bookmark-gt-auto-update-toggle. From Lisp,
use bookmark-gt-auto-update-set.
This mode proposes tags for a new bookmark based on its location.
The proposed tags become the initial input of the tag prompt, where
you can edit or clear them (see Tag reader). The tags come from
bookmark-gt-default-tags, which can be a single tag, a list of
tags, or a function of the newly created record that returns either:
(setq bookmark-gt-default-tags "work") ; one tag
(setq bookmark-gt-default-tags '("work" "urgent")) ; several tags
(setq bookmark-gt-default-tags ; a function
(lambda (record)
(cond ((string-prefix-p "/proj/" (bookmark-gt-filename-of record))
'("project"))
((eq (bookmark-gt-handler-type record) 'url)
'("web"))
(t nil))))If the function signals an error, bookmark-gt shows a warning and
proposes no tags. If bookmark-gt-prompt-for-tags-flag is nil,
there is no tag prompt and the proposed tags are stored as they
are.
This mode shows the tabs open in your browser as temporary URL bookmarks. It requires
browser-gt to be installed and connected to the browser.
The tab bookmarks are rebuilt each time they are about to be shown:
when bookmark-gt-jump starts reading, when the list buffer is
opened or reverted with g, when the mode is turned on while a
browser is connected, and when you run
M-x bookmark-gt-browser-tabs-refresh. There is no timer. A
refresh never prompts for tags and never causes the bookmark file
to be saved, since tab bookmarks are temporary.
Making a tab bookmark permanent with T in the list buffer turns it
into an ordinary URL bookmark that is saved like any other; because
the tab is still open, the next refresh adds a temporary bookmark
for it again. Deleting a tab bookmark deletes only the bookmark, and
the next refresh adds it again while the tab is open; as with every
bookmark-gt bookmark, deleting it does not affect what it points to.
Turning the mode off deletes the tab bookmarks it created, and
leaves alone the bookmarks of other packages that use browser-gt.
A tab bookmark’s visits and last-visited count the jumps
bookmark-gt made to it, not the browser’s own record of when the
tab was used, so a tab you have never jumped to is listed after
those you have. These values are kept when the tab bookmarks are
rebuilt, matched by browser name and tab id, but they are lost when
the browser restarts, when the mode is turned off, and when Emacs
exits.
Two options select which tabs are shown:
bookmark-gt-browser-tabs-browsers lists the browser clients to
ask (nil asks every connected browser), and
bookmark-gt-browser-tabs-filter is nil to keep every tab, a
regexp that the tab’s URL must match, or a predicate called with
the tab.
M-x bookmark-gt-list opens the list buffer. It is a
tabulated-list-mode buffer, so you can sort by clicking a column
header or with S on a column; s cycles the sort through all the
columns, including the marker columns.
| Col | Header | Meaning |
|---|---|---|
| 0 | * | * if the row is marked with m, D if it is flagged for deletion with d |
| 1 | ^ | ^ if the bookmark has the auto-update property |
| 2 | t | t if the bookmark is temporary |
| 3 | Name | The name, truncated at bookmark-gt-list-name-width (default 32) |
| 4 | Type | File, URL, EWW, Dired, Info, Org, PDF, BrowserTab, Function, Sequence, Kmacro, BkView, … |
| 5 | Group | Web, File, Doc, Code, Media or Other |
| 6 | Tags | The tags, separated by commas, truncated at bookmark-gt-list-tags-width (default 24) |
| 7 | Loc | The file name, or the URL for a bookmark without a file |
The name of a bookmark whose file no longer exists is shown struck
through (face bookmark-gt-face-missing-file). Remote (Tramp)
files are not checked.
| Key | Action |
|---|---|
RET | Jump |
o, C-o | Jump in another window |
TAB | Show the bookmark in another window, leaving point in the list |
m | Mark the row (with a numeric prefix, mark N rows) |
u | Unmark the row |
U | Unmark every row |
d | Flag the row for deletion |
x | Delete the flagged rows, after confirmation |
^ | Toggle auto-update (selection) |
T | Toggle temporary (selection) |
t e | Edit tags as a comma-separated list, adding and removing in one prompt (selection) |
t a | Add tags, one per prompt; empty RET or M-RET ends (selection) |
t r | Remove tags, completing over the tags present (selection) |
r | Rename |
R | Relocate: change the file name or URL |
a | Edit the annotation |
i | Show the record |
H | Show or hide temporary bookmarks in this buffer |
/ | Filter by type, group, tag or name regexp, or remove the filters |
s | Cycle the sort column |
V | Reset the view: sort by name, no filters, default display of temporary bookmarks |
g | Refresh browser tabs and auto-update positions (if those modes are on), then redraw |
C-x C-s | Save the bookmark file |
q | Quit |
Marks belong to the bookmark, not to the line, so they are kept when the buffer is sorted, reverted or redrawn after a change.
The commands marked selection in the table act on every row
marked with m, or on the row at point when no row is marked. For
example, after marking a few rows, t a adds the tags you type to
all of them, t r removes tags from all of them, and t e replaces
their tag lists. The prompts say how many bookmarks are affected,
and t e and t r offer every tag that appears on any of the
marked bookmarks.
T and ^ set the same value on every marked row: they turn the
property on for all of them, unless all of them already have it, in
which case they turn it off for all of them. A mixed selection
therefore becomes uniform on the first press.
A selection command clears the marks when it finishes. If you end a tag prompt without typing anything, nothing changes and the marks are kept.
Commands act only on the rows the buffer shows. A marked row that
is hidden by a filter or by H is left alone and keeps its mark,
so you can apply a command to part of a selection by narrowing the
view first. Tags offered by t e and t r, and the value a toggle
sets, are also computed from the visible rows only. If every
marked row is hidden, the command stops with “No selected bookmarks
in this view” instead of acting on the row at point.
The deletion flag D is separate from the selection: x is the
only command that uses it, and the selection commands ignore it.
x deletes only the flagged rows the buffer shows, and refuses
when all of them are hidden.
r, R, a, i and the jump commands act on the row at point and
ignore the marks.
The sort column, the display of temporary bookmarks and the active
filters are kept when you call bookmark-gt-list again in the same
session. To keep them across Emacs sessions as well, set
bookmark-gt-list-persist-state:
(setq bookmark-gt-list-persist-state t)The view is then saved to bookmark-gt-list-state-file (by default
(locate-user-emacs-file "bookmark-gt-list-state")) after every
change to it and when Emacs exits, and read the next time the list
buffer is created. Marks and the position of point are not saved.
V (bookmark-gt-list-reset-view) restores the default view.
bookmark-gt-jump replaces bookmark-jump, and C-x r b runs it
while bookmark-gt-mode is on. It reads the bookmark with
completing-read, so it works with any completion interface,
such as vertico or the default *Completions* buffer. When orderless
is loaded, three particles narrow the candidates:
@TYPEkeeps bookmarks of TYPE (@URL,@Info,@PDF, …);+GROUPkeeps bookmarks in GROUP (+Web,+File,+Doc, …);;TAGkeeps bookmarks that have TAG.
Particles are case-sensitive unless completion-ignore-case is
non-nil, so by default you type the names as they are displayed.
While reading, M-t adds a tag filter and restarts the read,
showing the active filters in the prompt; M-d removes the most
recent filter, and M-D removes all of them.
With marginalia loaded, each candidate shows its tags, its type and
its location (the file name or the URL). The annotation starts at
the first multiple of 10 columns past the widest candidate name, and
names are truncated at bookmark-gt-jump-name-max-width (default
58), so the annotation always starts at the same column during one
read. bookmark-gt positions the annotation itself, so
marginalia-align and marginalia-align-offset do not apply to it.
The location takes the columns the name, tags and type leave free,
so it is wider on a wide frame. Its width is limited by
bookmark-gt-jump-location-max-width: an integer is a number of
columns (default 100), a float is a fraction of
marginalia-field-width as marginalia computes it for the current
display (at most 80), and nil means no limit other than the free
space. The limit keeps a location that is very long but not
informative, such as a window configuration stored in a URL, from
taking every free column. A file location is truncated on the left
so that the file name stays visible, and a URL on the right so that
the scheme and host stay visible.
marginalia-field-width itself does not limit these fields,
because bookmark-gt gives marginalia the widths as column counts.
As a result the annotation can be wider than the half of the window
that marginalia normally allows.
bookmark-gt provides an API to create custom bookmark jumping functions.
The three entry points take keyword arguments only:
(cl-defun bookmark-gt-jump
(&key bookmark display-function bookmarks-list bookmarks-filter
sort-by preselect))
(cl-defun bookmark-gt-jump-other-window
(&key bookmark bookmarks-list bookmarks-filter sort-by preselect))
(cl-defun bookmark-gt-jump-tagged
(&key tag bookmark bookmarks-list bookmarks-filter sort-by preselect)):BOOKMARKis a bookmark name or record to jump to without prompting.:DISPLAY-FUNCTIONis called with the target buffer, as inbookmark-jump.:BOOKMARKS-LISTis the alist to choose from (defaultbookmark-alist), and:BOOKMARKS-FILTERis a predicate that a record must satisfy to be offered. Both are ignored when:BOOKMARKis given.:SORT-BYismru(most recently visited first),visits(most visited first) or nil (the order of the list). It defaults tobookmark-gt-jump-default-sort, which ismru.:PRESELECTis a positive integer N. When vertico is in use, the reader starts with the N-th candidate selected, so with MRU sorting:preselect 1selects the bookmark you visited before the last one.:TAG(forbookmark-gt-jump-tagged) is the tag filter the read starts with.
;; Jump to a known bookmark
(bookmark-gt-jump :bookmark "my-bookmark")
;; Display the target in another frame
(bookmark-gt-jump :display-function #'switch-to-buffer-other-frame)
;; Choose among file bookmarks only
(bookmark-gt-jump :bookmarks-filter #'bookmark-gt-handler-file-p)
;; Choose among file bookmarks tagged "urgent"
(bookmark-gt-jump-tagged :tag "urgent"
:bookmarks-filter #'bookmark-gt-handler-file-p)bookmark-gt-jump-candidate-format-function (default
bookmark-gt-jump-candidate-default) builds each candidate string
from a record. A replacement must put the record in the
bookmark-gt-record text property and the name in
bookmark-gt-name, and may put the narrowing particles in
bookmark-gt-particles; see the default function’s docstring.
Without bookmark-gt-record, the reader has to find the selected
bookmark by name, and cannot tell apart two bookmarks with the same
name.
M-x bookmark-gt-create-url prompts for a URL (defaulting to the
URL at point), a name and tags. It can also be called from Lisp:
(bookmark-gt-create-url "https://example.org" "Example" '("web" "reference"))Jumping opens the URL with browse-url, so it follows your
browse-url-browser-function and browse-url-handlers settings.
The built-in Dired has no bookmark handler, so bookmark-gt provides
bookmark-gt-handler-dired-jump. A Dired bookmark records, and its
jump restores:
dired-directory, so plain directories, wildcards such as/tmp/*.eland explicit file lists are all restored as they were;dired-marked, the marked files and their mark characters;dired-subdirs, the subdirectories inserted withi;dired-hidden-dirs, the subdirectories hidden with$;dired-switches, thelsswitches in effect.
These keys are the ones bookmark+ uses (bmkp-jump-dired), so Dired
bookmarks can be moved between the two packages in either direction.
Records with bookmark+’s handler are classified as Dired, and
M-x bookmark-gt-migrate-from-bookmark-plus converts them to
bookmark-gt’s handler (see Migrating from bookmark+).
A bookmark created in a virtual Dired buffer (M-x dired-virtual,
or V in dired-x) also stores the buffer’s listing under
dired-listing and sets dired-virtual. Jumping recreates the
same buffer from the stored listing, even if the directory no
longer exists. bookmark+ does not do this; it opens the directory
as an ordinary Dired buffer.
Because the bookmark file is read whole at startup and written whole
on every save, the listing is limited to
bookmark-gt-dired-virtual-max-size bytes (default 524288, that is
512 KB). Creating a bookmark in a larger virtual Dired buffer is an
error.
A function bookmark stores a function (a symbol or a lambda) under
the function key, and jumping calls it. M-x
bookmark-gt-create-function prompts for the name and the command.
From Lisp:
(bookmark-gt-create-function "rebuild" #'my-project-rebuild)
(bookmark-gt-create-function "flip-theme" (lambda () (my-toggle-theme)))A keyboard-macro bookmark stores a vector of key events under the
kmacro key, and jumping replays it with execute-kbd-macro, using
the prefix argument as the repeat count.
M-x bookmark-gt-create-kmacro offers your named keyboard macros,
plus [last-kbd-macro] for the most recently defined one, which is
the default when it exists; it is an error if there is no macro at
all. A named macro is a symbol whose function definition is a
string or vector, or that has a kmacro property, as created by
M-x kmacro-name-last-macro. From Lisp:
(bookmark-gt-create-kmacro "type-hi" [?h ?i])
(bookmark-gt-create-kmacro "type-abc" "abc") ; parsed by `read-kbd-macro'bookmark+ stores keyboard macros as function bookmarks. bookmark-gt gives them a type of their own so that the list buffer and the jump reader can distinguish them, which means a bookmark+ macro bookmark is shown as a Function bookmark in bookmark-gt.
A sequence bookmark jumps to a list of bookmarks in order. M-x
bookmark-gt-create-sequence prompts for its name and then for
existing bookmarks, one per prompt, until you enter an empty input.
From Lisp:
(bookmark-gt-create-sequence "morning-workspace"
'("inbox" "todo.org" "calendar"))The members are stored under the sequence key. A member name that
matches exactly one bookmark is replaced by that bookmark’s id (see
Record identity), so the sequence still works after the member is
renamed.
bookmark-gt provides a way to specify how to open bookmarks.
bookmark-gt-file-type-handlers maps file-name regexps to bookmark
handler functions. Jumping to a file bookmark whose filename
matches one of the regexps calls the associated function with the
record, instead of visiting the file. The first matching entry is
used. For example, to open PDF and video files with macOS’s open
command:
(defun my-mac-open (bookmark)
"Open BOOKMARK's file with macOS's `open' command."
(call-process "open" nil 0 nil
(bookmark-prop-get bookmark 'filename)))
(setq bookmark-gt-file-type-handlers
'(("\\.pdf\\'" . my-mac-open)
("\\.\\(mp4\\|mkv\\)\\'" . my-mac-open)))It is possible to create a bookmark to the current state of the *Bookmarks-gt List* buffer.
A view bookmark stores the list buffer’s filters, sort column and
display of temporary bookmarks (under the filters, sort-key and
show-temp keys). To create one, set up the list buffer the way
you want it and run M-x bookmark-gt-create there. Jumping to it
opens the list buffer with that view. Marks and the position of
point are not stored.
bookmark-gt-tags-read asks for tags one at a time, completing over
the tags already in use, most recently used first. Each non-empty
RET adds a tag and asks for the next; an empty RET finishes, and
M-RET adds the current input and finishes. The prompt shows the
tags entered so far, as in Tags [foo,bar] (M-RET or empty RET to
finish):.
The creation commands (bookmark-gt-create,
bookmark-gt-create-url, bookmark-gt-create-function,
bookmark-gt-create-kmacro and bookmark-gt-create-sequence)
compute the tags of a new bookmark in three steps:
- if
bookmark-gt-default-tags-modeis on, the default tags; - if
bookmark-gt-prompt-for-tags-flagis non-nil (the default), the tag reader, starting with the tags from step 1; - the functions on
bookmark-gt-create-tag-reader-hook, which receive the tags from step 2.
These steps run after the name has been accepted, so a name that
bookmark-gt-allow-same-name-bookmarks refuses is reported before
you are asked for tags.
From Lisp, the TAGS argument of a creation command is either a list
of tags, which is stored as given with no prompt, or t, which runs
the three steps (interactive calls pass t):
(bookmark-gt-create-url "https://example.org" "example" '("web")) ; stores ("web")
(bookmark-gt-create-url "https://example.org" "example" t) ; runs the stepsbookmark-gt-create-non-file, which creates a record with a given
handler, never runs these steps; the record gets the tags entry
of its PROPS argument, if any.
A bookmark name is a label, not an identifier, so several bookmarks
may share one, such as a todo bookmark in each of several
projects. Two bookmarks with the same name and the same destination,
however, are almost always a mistake.
bookmark-gt-allow-same-name-bookmarks decides whether
bookmark-gt-create may reuse a name:
| Value | Creating with a name already in use |
|---|---|
never | refused |
different-destination (default) | allowed if the two point at different files or URLs, refused if at the same |
always | allowed |
The destination is the file or URL, not the position, so two
bookmarks at different places in one file have the same destination.
A refused name is an error that names the conflicting bookmark; the
new bookmark is not stored under a modified name. If you meant to
move the existing bookmark, use bookmark-gt-update, as the error
message suggests.
The names in bookmark-gt-unique-names (by default those of
org-capture and org-refile) always identify a single bookmark,
whatever the setting. For handlers in
bookmark-gt-unique-name-handlers, storing a bookmark with the name
of an existing bookmark of the same handler replaces it.
Bookmarks that share a name are displayed with a suffix, as in
todo and todo<2>, the way Emacs names buffers. The suffix is
only displayed: the bookmark file contains the name you typed, so
deleting or renaming one of the bookmarks renumbers the others.
A bookmark file can contain names the setting forbids, if it was
written by the built-in bookmark package, by bookmark-gt with a
different setting, or on another machine. When such a file is
loaded, the bookmarks the setting forbids are left out of
bookmark-alist, and a warning shows each of them in full, since
until the file is saved the warning is the only other copy. The
first bookmark with a given name is always kept, and under the
default setting a later one is kept if it points somewhere no kept
bookmark does. The same check runs when the list buffer is opened
or reverted and when the jump reader starts, so it also catches
bookmarks created some other way, such as by bookmark-set called
from Lisp.
The bookmarks left out are still in the file, and they are removed
from it the next time it is saved. To keep them, set the option to
always and load the file again before saving. Leaving them out
does not by itself cause the file to be saved.
First count the bookmarks with that name:
(seq-filter (lambda (r)
(equal (substring-no-properties (car r)) "todo"))
bookmark-alist)If there are two, the list buffer is not showing one of them,
either because a filter is active (filters can be kept from an
earlier session; V removes them), or because one of them is
temporary and temporary bookmarks are hidden (H shows them;
T is different, it makes the bookmark at point temporary or
permanent).
If there is one, the second was never stored: either
bookmark-gt-create refused it, with an error at the time, or it
was left out when the file was loaded, with a warning listing it
(see the previous section).
The built-in bookmark-get-bookmark looks a name up with assoc,
so the built-in commands act on the first bookmark with that name.
bookmark-gt’s commands work with records: given a record, they act
on it, and given a name that several bookmarks share, they ask which
one. Selecting the second of two todo bookmarks in the jump
reader or the list buffer therefore jumps to, renames, relocates or
deletes that bookmark, and the jump counts as a visit to it.
While bookmark-gt-mode is on, M-x bookmark-delete,
bookmark-rename, bookmark-jump and bookmark-set run
bookmark-gt’s versions. The functions themselves are not changed,
because packages depend on their behavior: org-capture and
org-refile, for example, store a bookmark under a fixed name each
time and rely on bookmark-set replacing the previous one. From
Lisp, bookmark-gt-jump-record, bookmark-gt-rename-record and
bookmark-gt-delete-record take a record, and signal an error when
given a name.
Each bookmark has a bookmark-gt-id, a symbol assigned when the
bookmark is created; bookmarks that lack one (for example, because
another package wrote them) get one when the bookmark file is
loaded, the list buffer is drawn or the jump reader starts. The id
lets a reference outlive a rename, which is why sequence bookmarks
store their members by id. You never type an id; it appears only in
i in the list buffer and in the bookmark file, and the built-in
bookmark package ignores it. A file copied between machines can
contain the same id twice; a bookmark is looked up by its id when it
has one, and by its name otherwise.
| Command | Changes | Run it from |
|---|---|---|
bookmark-gt-update | where it points: to point | the new location |
bookmark-gt-relocate | where it points: to a file or URL you type | anywhere |
bookmark-gt-rename | its name | anywhere |
Each command takes a bookmark record, name or id, and prompts when given none. Given a name that several bookmarks share, it asks which one.
bookmark-gt-update records the current location and stores it in
the existing bookmark. The bookmark keeps its name, id, tags,
annotation, creation time and visit history; everything that
describes where it points is replaced, so data left from its
previous type (a PDF page, an Org heading id, Dired marks) is
removed. It asks for confirmation before changing the bookmark’s
type, for example from PDF to Org. It cannot update URL, function,
keyboard-macro or sequence bookmarks, since they have no location
in a buffer; use bookmark-gt-relocate for those.
bookmark-gt-relocate asks for the new target instead of recording
the current location, so it works without visiting the target. For
a file bookmark it reads a file name, starting from the current one,
and keeps the position, since the usual reason to relocate is a file
that was moved. For a URL bookmark, including a browser-tab
bookmark, it reads a URL. Other bookmarks cannot be relocated. It
refuses a target of a different type (an Org file for a PDF
bookmark, for example), because the bookmark’s handler could not
open it; use bookmark-gt-update to change the type. In the list
buffer, R relocates the bookmark at point.
bookmark-gt-rename renames the bookmark you select, not the first
one with its name. The new name is checked the same way as a new
bookmark’s name (see Bookmarks that share a name). In the list
buffer, r renames the bookmark at point.
M-x bookmark-gt-delete deletes the bookmark you select, not the
first one with its name. If a sequence bookmark refers to it, the
command tells you before deleting, since that reference will no
longer work. In the list buffer, d flags rows and x deletes
them.
M-x bookmark-gt-cycle-next and M-x bookmark-gt-cycle-prev move
point to the next or previous bookmark in the current file, ordered
by position, wrapping around at either end and showing the
bookmark’s name. Bookmarks without a numeric position, such as
Dired bookmarks, are skipped. Cycling does not depend on
highlighting being on. Example bindings:
(global-set-key (kbd "C-c n") #'bookmark-gt-cycle-next)
(global-set-key (kbd "C-c p") #'bookmark-gt-cycle-prev)While bookmark-gt-mode is on, each bookmark is highlighted in the
buffers that visit its file, using bookmark-gt-face-highlight
(which inherits from hl-line). A bookmark at a point highlights
its line, and a region bookmark highlights the lines of its region;
moving the mouse over the highlight shows the bookmark’s name.
Highlights are added when a file is visited and updated after each
change to a bookmark. A bookmark without a numeric position, such
as an Org heading bookmark, is highlighted at the place its last
jump arrived, once you have jumped to it. Highlights are not saved,
and they are removed when the mode is turned off. To turn them off
while keeping the mode on, set bookmark-gt-highlight-enable to
nil.
If the region is active when you run bookmark-gt-create, the
bookmark stores the region and selects it again after a jump. The
record stores the start in position and the end in
end-position, plus bookmark-gt-region-context-size characters
(default 40) before and after the end, under
front-context-region-string and rear-context-region-string,
which locate the end again if the text has changed. These keys are
the ones bookmark+ uses; the built-in bookmark package ignores them
and jumps to position. To neither store nor restore regions, set
bookmark-gt-use-region to nil.
Every jump increments the bookmark’s visits count and sets its
last-visited time, which is what the jump reader’s mru and
visits sorting use. These changes do not mark the bookmark file
as modified, so jumping never causes a save; they are written the
next time the file is saved for another reason.
While bookmark-gt-mode is on, renaming a file with rename-file,
which Dired’s R also uses, changes every bookmark that points at
the old file name to point at the new one. Renaming a directory
changes only bookmarks that point at the directory itself, not at
files inside it. Renames to a backup file name are ignored, because
Emacs renames a file to its backup name when it saves it, and the
bookmark should stay with the file. To turn rename tracking off,
set bookmark-gt-track-renames to nil.
bookmark-gt-handler-alist maps each handler function to a
description of its bookmark type:
(HANDLER . (:type TYPE-SYMBOL :name STRING :group GROUP-SYMBOL
:face FACE :doc STRING))Several handlers can share a type; URL bookmarks, for example, have three handler names. bookmark-gt registers file, URL, EWW, Dired, Info, Org, Org-roam (org-roam-gt), PDF, browser tab, Magit, Help, Image and EPUB (nov.el) bookmarks. To register a new handler, or another name for an existing type:
(bookmark-gt-handler-register
'(my-custom-jump my-legacy-jump-handler)
(list :type 'custom :name "Custom" :group 'other
:face 'bookmark-gt-face-file
:doc "My custom bookmark type."
:preview #'my-preview-fn)) ; optionalThe optional :preview function is what TAB in the list buffer
calls with the record, inside save-selected-window; without it,
TAB jumps to the bookmark in another window. A preview function
lets you, for example, show a URL in EWW while RET still opens it
in the external browser.
A handler that is not registered is classified automatically. If
it has a bookmark-handler-type property, as bookmark-bmenu-list
expects, that is its type name. Otherwise its name is used without
the usual suffixes (-bookmark-jump-handler, -bookmark-jump,
-jump-handler, --handle-bookmark), so foo-bookmark-jump is
shown as type “Foo”. Either way, its group is other.
Each registered type has a predicate:
bookmark-gt-handler-file-p, -url-p, -eww-p, -dired-p,
-info-p, -org-p, -org-roam-p, -pdf-p, -browser-tab-p,
-magit-p, -help-p, -image-p, -epub-p, -function-p,
-sequence-p, -kmacro-p and -view-p, each equivalent to
(eq (bookmark-gt-handler-type record) 'TYPE).
Groups combine several types into one category, so that you can filter by “web” instead of by URL, EWW and browser tab separately. A bookmark’s group is computed from its handler’s registration and is not stored in the record.
| Symbol | Name | Types |
|---|---|---|
web | Web | url, eww, browser-tab |
file | File | file, dired |
doc | Doc | info, org, org-roam, pdf, help, epub |
code | Code | magit |
media | Media | image |
other | Other | everything else |
bookmark-gt-group-alist holds the groups. To add one:
(bookmark-gt-group-register
'science '(:name "Sci" :doc "Science and research bookmarks."))The group is shown in the list buffer’s Group column, can be
filtered with /, and is matched by the +GROUP particle in the
jump reader. (bookmark-gt-handler-group RECORD) returns a
record’s group.
bookmark-gt-create-name-reader-hookruns inbookmark-gt-createbefore the name prompt. Each function is called with the suggested name and the new record’s data, and can return a different suggestion; the first non-nil value is used.bookmark-gt-create-tag-reader-hookis the last step of the tag computation (see Tag reader); it does not run inbookmark-gt-create-non-file. Each function is called with the record and the tags so far, and returns the tags passed to the next function.bookmark-gt-record-changed-hookruns after every change to a bookmark, with the record and a symbol naming the change:create,update,relocate,rename,tags,temp,auto-updateordelete.bookmark-gt-jump-before-read-hookruns once each timebookmark-gt-jump,bookmark-gt-jump-other-windoworbookmark-gt-jump-taggedis about to prompt (not when:BOOKMARKis given, and not again when a tag filter restarts the read). Use it to rebuild bookmarks that must be current when the reader shows them;bookmark-gt-browser-tabs-modeaddsbookmark-gt-browser-tabs-refreshto it.bookmark-gt-list-before-read-hookruns when the list buffer is opened or reverted, before the rows are drawn.bookmark-gt-browser-tabs-modeaddsbookmark-gt-browser-tabs-refreshto it, andbookmark-gt-auto-update-modeaddsbookmark-gt-auto-update-tick.bookmark-gt-session-only-propslists record keys whose values are valid only while another program is running, such as a browser tab id. When a temporary bookmark is made permanent, these keys are removed from it, so they are never saved.bookmark-gt-browser-tabs-moderegisters the three keys its tab bookmarks use.bookmark-gt-filter-alistandbookmark-gt-sort-alisthold the list buffer’s filters (for/) and sort orders.
bookmark-gt reads and writes these record keys with the same meaning as bookmark+, so either package can read the other’s bookmark file:
| Key | Meaning |
|---|---|
tags | List of tag strings |
bmkp-temp | The bookmark is temporary |
auto-update | The position is kept up to date |
visits | Number of visits |
last-visited | Time of the last visit |
created | Time of creation |
last-modified | Time of the last change |
Two differences are handled when reading. bookmark+ stores the
string " - no file -" in filename for bookmarks without a file,
which bookmark-gt-filename-of treats as no file name; bookmark-gt
omits filename for such bookmarks. bookmark+ stores a URL under
location, while bookmark-gt uses url; bookmark-gt-url-of reads
both. bookmark-gt adds one key of its own, bookmark-gt-id (see
Record identity), which bookmark+ and the built-in bookmark
package ignore.
Bookmarks saved by bookmark+ name handler functions that exist only
when bookmark+ is loaded (bmkp-jump-dired, bmkp-jump-url-browse,
bmkp-jump-url-browse-other-window and bmkp-gt-browsel-tabs-jump).
bookmark-gt classifies them correctly in the list buffer and the jump
reader, but jumping to them fails because the function is not
defined. M-x bookmark-gt-migrate-from-bookmark-plus converts them
once:
;; Changes `bookmark-alist' only; the file is not written.
(bookmark-gt-migrate-from-bookmark-plus)
;; Check the result in M-x bookmark-gt-list, then save:
(bookmark-save)For each bookmark+ record, the migration replaces the handler with
bookmark-gt’s, moves a URL from location to url, and removes the
" - no file -" placeholder from filename. It also removes keys
that bookmark-gt does not use: bmkp-gt-load-index, buffer-name,
front-context-region-string, rear-context-region-string, and an
empty annotation or tags. It keeps a real filename,
position, front-context-string, rear-context-string, visits,
last-visited, created, last-modified and the Dired keys, which
bookmark-gt’s Dired handler reads the same way bookmark+’s did.
Records already in bookmark-gt’s form, and plain file bookmarks, are
not changed. Keep a copy of your bookmark file before migrating.
| Variable | Default | Description |
|---|---|---|
bookmark-gt-list-name-width | 32 | Width of the list buffer’s Name column; longer names are truncated. |
bookmark-gt-list-type-width | 12 | Width of the Type column. |
bookmark-gt-list-tags-width | 24 | Width of the Tags column. |
bookmark-gt-list-buffer-name | "*Bookmarks-gt List*" | Name of the list buffer. |
bookmark-gt-list-selection-mark | ?* | Character shown for rows marked with m. |
bookmark-gt-list-deletion-mark | ?D | Character shown for rows flagged with d. |
bookmark-gt-list-default-show-temp | t | Whether a new list buffer shows temporary bookmarks; H changes it per buffer. |
bookmark-gt-list-persist-state | nil | Whether the list buffer’s view is saved across sessions. |
bookmark-gt-jump-name-max-width | 58 | Width at which the jump reader truncates names, so that long names leave room for the annotation. |
bookmark-gt-jump-location-max-width | 100 | Limit on the width of the location in the jump annotation: columns (integer), a fraction of marginalia-field-width (float), or no limit (nil). |
bookmark-gt-jump-default-sort | mru | Sort order of bookmark-gt-jump when :sort-by is not given: mru, visits, or nil for the list’s order. |
bookmark-gt-dired-virtual-max-size | 524288 | Largest virtual Dired listing, in bytes, that a bookmark can store. |
bookmark-gt-auto-update-interval | 60 | Seconds of idle time between updates of auto-update bookmarks. |
bookmark-gt-track-renames | t | Whether renaming a file updates the bookmarks pointing at it. |
bookmark-gt-default-tags | nil | Tags proposed by bookmark-gt-default-tags-mode: a string, a list of strings, or a function of the record. |
bookmark-gt-prompt-for-tags-flag | t | Whether creating a bookmark interactively prompts for tags; default tags and bookmark-gt-create-tag-reader-hook apply either way. |
bookmark-gt-allow-same-name-bookmarks | different-destination | When a new bookmark may reuse a name: never, different-destination or always. |
bookmark-gt-unique-names | ("\\`org-capture-last-stored\\'" "\\`org-refile-last-stored\\'") | Regexps of names that always identify a single bookmark, whatever the previous option says. |
bookmark-gt-unique-name-handlers | (burly-bookmark-handler) | Handlers whose bookmarks are one per name: storing one replaces the existing bookmark of that name and handler. |
bookmark-gt-auto-temp-names | ("\\`org-capture-last-stored\\'" "\\`org-refile-last-stored\\'") | Regexps of names whose bookmarks are made temporary when stored. |
bookmark-gt-highlight-enable | t | Whether bookmarks are highlighted in the buffers visiting their files. |
bookmark-gt-file-type-handlers | nil | File-name regexps mapped to the functions that open matching file bookmarks. |
bookmark-gt-browser-tabs-browsers | nil | Browser clients asked for tabs, such as ("chrome" "firefox"); nil asks every connected browser. |
bookmark-gt-browser-tabs-filter | nil | Which tabs to keep: nil for all, a regexp the URL must match, or a predicate called with the tab. |
bookmark-gt owes a great deal to Drew Adams and his bookmark+ package, in design and in code. Most of its features (tags, URL, EWW, region, function, sequence and keyboard-macro bookmarks, temporary bookmarks, visit tracking, highlighting and filtering by tag) first appeared in bookmark+.
The URL handler (bookmark-gt-handler-url-jump) and the Dired
handler (bookmark-gt-handler-dired-jump) were adapted from
bookmark+’s bmkp-jump-url-browse and bmkp-jump-dired. The record
keys tags, bmkp-temp, auto-update, visits, last-visited,
location, front-context-region-string and
rear-context-region-string are bookmark+’s, so these fields are
kept when a bookmark file is used by both packages. The one
exception is the " - no file -" placeholder, which bookmark-gt
reads but does not write (see Data compatibility with bookmark+);
whether bookmark+ accepts a record without filename has not been
tested.
bookmark-gt is a rewrite, not a fork: it is built on
tabulated-list-mode and on registries of handlers, groups, filters
and sort orders. Its features, its design ideas and the handler code
it adapts come from Drew’s work.
GPL-3.0-or-later. See LICENSE.