8000 GitHub - 0xhenrique/esb: Emacs Simple Bookmark - This is a simple encrypted bookmark manager for Emacs that stores bookmarks in an encrypted file suitable for syncing via Git. It uses GPG encryption to keep your bookmarks secure while allowing you to store them in public repositories.
[go: up one dir, main page]
More Web Proxy on the site http://driver.im/
Skip to content
/ esb Public

Emacs Simple Bookmark - This is a simple encrypted bookmark manager for Emacs that stores bookmarks in an encrypted file suitable for syncing via Git. It uses GPG encryption to keep your bookmarks secure while allowing you to store them in public repositories.

License

AGPL-3.0 license
1 star 1 fork Branches Tags Activity
Star
Notifications You must be signed in to change notification settings

0xhenrique/esb

BranchesTags

Folders and files

NameName
Last commit message
Last commit date

Latest commit

 

History

8 Commits
LICENSE
LICENSE
 
 
README.org
README.org
 
 
esb.el
esb.el
 
 

Repository files navigation

Emacs Simple Bookmark

Overview

This is a simple encrypted bookmark manager for Emacs that stores bookmarks in an encrypted file suitable for syncing via Git. It uses GPG encryption to keep your bookmarks secure while allowing you to store them in public repositories.

This README has become quite extensive, but I hope it addresses most of the doubts that may arise regarding its usage or potential issues that may occur. Nonetheless, please do not hesitate to open an issue if you encounter any problems. Pull requests are always welcome as well.

Features

  • Encrypted bookmark storage using GPG (with plain text option)
  • Simple JSON format
  • Git-friendly
  • Built-in Emacs integration
  • Tag support
  • Filtering by tags
  • No external dependencies beyond GPG (you probably already have that)

Installation and Setup

1. GPG Configuration

Check if GPG is installed

gpg --version

If GPG is not installed… Install it!

Generate a GPG key (if you don’t have one)

gpg --full-generate-key

Choose the following options:

  1. RSA and RSA (default)
  2. 4096 bits (recommended for long-term use)
  3. Key validity (0 = no expiration, or set as preferred)
  4. Enter name and email address
  5. Set a strong passphrase

Verify if your key was created

gpg --list-secret-keys --keyid-format LONG

2. Emacs Configuration

Basic setup

Add to your Emacs configuration:

;; Load esb.el (if not installing via package manager)
(load-file "~/path/to/esb.el")

;; Optional: customize bookmark file location
(setq esb-bookmarks-file "~/bookmarks/bookmarks.gpg")

;; Optional: use plain text instead of GPG encryption
;; (setq esb-storage-backend 'plain)

Key Binding Setup

ESB doesn’t define any global key bindings by default to avoid conflicts. You need to define your own key bindings.

Key bindings I use

(global-set-key (kbd "C-c C-b s") 'esb-select-bookmark)
(global-set-key (kbd "C-c C-b a") 'esb-add-bookmark)
(global-set-key (kbd "C-c C-b d") 'esb-delete-bookmark)
(global-set-key (kbd "C-c C-b l") 'esb-list-bookmarks)
(global-set-key (kbd "C-c C-b e") 'esb-edit-bookmark)
(global-set-key (kbd "C-c C-b t") 'esb-list-tags)
(global-set-key (kbd "C-c C-b r") 'esb-reload-bookmarks)
(global-set-key (kbd "C-c C-b i") 'esb-initialize)

3. Git Repository Setup

Initialize bookmark repository

# Create directory for bookmarks
mkdir ~/bookmarks
cd ~/bookmarks

# Initialize git repository
git init

# Create .gitignore (optional - exclude temporary files)
echo "*~" > .gitignore
echo "*.bak" >> .gitignore

# Initial commit
git add .gitignore
git commit -m "your commit message"

Connect to GitHub

# Create repository on GitHub (or any provider you prefer) first, then:
git remote add origin git@github.com:yourusername/bookmarks.git

# Push initial commit
git push -u origin master

Configure bookmark file path

Update your Emacs config to point to the git repository:

(setq esb-bookmarks-file "~/bookmarks/bookmarks.gpg")

Usage

Available Functions

All functions are autoloaded and can be called via M-x:

  • esb-select-bookmark - Select bookmark and copy URL to clipboard (prefix arg to filter by tag)
  • esb-add-bookmark - Add new bookmark with URL, description and tags are optional
  • esb-delete-bookmark - Delete bookmark by selection
  • esb-list-bookmarks - Display all bookmarks in a buffer (prefix arg to filter by tag)
  • esb-edit-bookmark - Edit bookmark description and tags
  • esb-list-tags - Display all available tags with bookmark counts
  • esb-reload-bookmarks - Reload bookmarks from file (after git pull)
  • esb-initialize - Initialize empty bookmark file

Tag Usage

Adding tags

When adding bookmarks, you can specify tags as comma-separated values:

  • Single tag: work
  • Multiple tags: work, api, reference
  • Tags with spaces: machine learning, data science

Filtering by tags

Use prefix argument (C-u) with list and select functions:

  • C-u C-c C-b l - List bookmarks filtered by tag
  • C-u C-c C-b s - Select bookmark filtered by tag

Basic workflow

First time setup

  1. M-x esb-initialize - Create empty encrypted bookmark file
  2. M-x esb-add-bookmark - Add your first bookmark with tags
  3. Commit and push to GitHub

Adding bookmarks with tags

M-x esb-add-bookmark
Bookmark URL: https://api.github.com
Description (optional): GitHub API Documentation
Tags (comma-separated, optional): work, api, reference

Syncing across machines

# Pull latest bookmarks
git pull

# In Emacs: reload bookmarks
M-x esb-reload-bookmarks

# After making changes: commit and push
git add bookmarks.gpg
git commit -m "your message" 
git push

Git Workflow

Adding bookmarks

# After adding bookmarks in Emacs
git add bookmarks.gpg
git commit -m "add new bookmarks, etc..."
git push

Syncing on different machines

# Pull latest changes
git pull

# Reload in Emacs
M-x esb-reload-bookmarks

Note: GPG files can’t be automatically merged, so avoid simultaneous edits when possible.

Security Considerations

GPG Key Management

  • Keep your private key secure and backed up (VERY IMPORTANT!)
  • Use a strong passphrase for your GPG key (you can cache it)
  • The same GPG key must be available on all machines where you use bookmarks

Repository Security

  • Your encrypted bookmark file is safe to store in public repositories
  • The repository only contains the encrypted file, not plaintext bookmarks

Best Practices

  • Never commit your GPG private key to the repository (ALSO VERY IMPORTANT!)
  • Regularly backup your GPG keys! (ALSO VERY IMPORTANT!)

Configuration Options

Customizable Variables

;; Bookmark file location
(setq esb-bookmarks-file "~/path/to/bookmarks.gpg")

;; Storage backend (gpg, plain, or custom function)
(setq esb-storage-backend 'gpg)  ; default: GPG encrypted
;; (setq esb-storage-backend 'plain)  ; plain text

;; GPG program path (if needed)
(setq epg-gpg-program "/usr/local/bin/gpg")

;; Cache passphrase
(setq epa-file-cache-passphrase-for-symmetric-encryption t)

Storage Backends

GPG (default)

Stores bookmarks in GPG-encrypted files, suitable for public repositories like Github.

Plain Text

Stores bookmarks in plain JSON files. Useful for local-only usage or when GPG is not available.

(setq esb-storage-backend 'plain)
(setq esb-bookmarks-file "~/bookmarks/bookmarks.json")

File Format

The encrypted file is just a simple JSON array:

[
  {
    "url": "https://example.com",
    "description": "Example website",
    "tags": ["work", "reference"]
  },
  {
    "url": "https://github.com",
    "description": null,
    "tags": ["code", "git"]
  },
  {
    "url": "https://api.example.com",
    "description": "API docs",
    "tags": null
  }
]

Troubleshooting

Key Binding Conflicts

If you encounter key binding conflicts:

  1. Check what’s currently bound: C-h k [key-sequence]
  2. Choose different keys for ESB functions
  3. Use global-set-key to define exactly what you want

GPG Issues

  • Ensure GPG is properly configured and your key is available
  • Check that epa-file is working: try opening any .gpg file
  • Verify GPG agent is running if using GUI Emacs

Invalid Bookmark Errors

ESB now validates bookmarks and will skip invalid entries:

  • URLs must start with http:// or https://
  • Tags must be strings if present
  • Use M-x esb-reload-bookmarks if you manually edit the file (NOT RECOMMENDED!)

License

This is a simple encrypted bookmark manager for Emacs that stores bookmarks in an encrypted file suitable for syncing via Git. It uses GPG encryption to keep your bookmarks secure while allowing you to store them in public repositories.

Copyright (C) 2025 0xhenrique

This program is free software: you can redistribute it and/or modify it under the terms of the GNU Affero General Public License as published by the Free Software Foundation, either version 3 of the License, or (at your option) any later version.

This program is distributed in the hope that it will be useful, but WITHOUT ANY WARRANTY; without even the implied warranty of MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the GNU Affero General Public License for more details.

You should have received a copy of the GNU Affero General Public License along with this program. If not, see https://www.gnu.org/licenses/.

About

Emacs Simple Bookmark - This is a simple encrypted bookmark manager for Emacs that stores bookmarks in an encrypted file suitable for syncing via Git. It uses GPG encryption to keep your bookmarks secure while allowing you to store them in public repositories.

Resources

Readme

License

AGPL-3.0 license
Activity

Stars

1 star

Watchers

0 watching

Forks

1 fork
Report repository

Releases

No releases published

Packages

No packages published

Languages
0