From 9943018c2e5d015997bf7adcaffd5d8f22e851c0 Mon Sep 17 00:00:00 2001 From: 0xhenrique Date: Fri, 30 May 2025 21:50:22 +0100 Subject: update keybinds and readme --- README.org | 95 ++++++++++++++++++++++++++++++++++++++++---------------------- esb.el | 26 ++++++++--------- 2 files changed, 74 insertions(+), 47 deletions(-) diff --git a/README.org b/README.org index 9ced5fa..253d00f 100644 --- a/README.org +++ b/README.org @@ -6,6 +6,8 @@ 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 @@ -34,7 +36,7 @@ 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 your real name and email address +4. Enter name and email address 5. Set a strong passphrase *** Verify if your key was created @@ -48,14 +50,30 @@ gpg --list-secret-keys --keyid-format LONG Add to your Emacs configuration: #+BEGIN_SRC elisp -;; Load esb.el +;; Load esb.el (if not installing via package manager) (load-file "~/path/to/esb.el") -;; Enable esb-mode globally -(esb-mode 1) - ;; Optional: customize bookmark file location (setq esb-bookmarks-file "~/bookmarks/bookmarks.gpg") + +;; Optional: enable global minor mode (doesn't bind keys by default) +(esb-mode 1) +#+END_SRC + +*** Key Binding Setup + +ESB doesn't define any global key bindings by default to avoid conflicts. You need to define your own key bindings. + +**** Recommended key bindings +#+BEGIN_SRC elisp +;; My personal recommendation - follows Emacs conventions +(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 r") 'esb-reload-bookmarks) +(global-set-key (kbd "C-c C-b i") 'esb-initialize) #+END_SRC ** 3. Git Repository Setup @@ -75,7 +93,7 @@ echo "*.bak" >> .gitignore # Initial commit git add .gitignore -git commit -m "Initial commit" +git commit -m "your commit message" #+END_SRC *** Connect to GitHub @@ -95,24 +113,29 @@ Update your Emacs config to point to the git repository: * Usage -** Key bindings -- ~C-c b s~ - Select bookmark (copy URL to clipboard) -- ~C-c b a~ - Add new bookmark -- ~C-c b d~ - Delete bookmark -- ~C-c b l~ - List all bookmarks -- ~C-c b e~ - Edit bookmark description -- ~C-c b r~ - Reload bookmarks from file -- ~C-c b i~ - Initialize empty bookmark file - -** Interactive functions -All functions can also be called via ~M-x~: -- ~esb-select-bookmark~ -- ~esb-add-bookmark~ -- ~esb-delete-bookmark~ -- ~esb-list-bookmarks~ -- ~esb-edit-bookmark~ -- ~esb-reload-bookmarks~ -- ~esb-initialize~ +** Available Functions + +All functions are autoloaded and can be called via ~M-x~: + +- ~esb-select-bookmark~ - Select bookmark and copy URL to clipboard +- ~esb-add-bookmark~ - Add new bookmark with URL and optional description +- ~esb-delete-bookmark~ - Delete bookmark by selection +- ~esb-list-bookmarks~ - Display all bookmarks in a buffer +- ~esb-edit-bookmark~ - Edit bookmark description +- ~esb-reload-bookmarks~ - Reload bookmarks from file (after git pull) +- ~esb-initialize~ - Initialize empty bookmark file + +** Key Binding Reference + +Using the recommended key bindings: + +- ~C-c C-b s~ - Select bookmark (copy URL to clipboard) +- ~C-c C-b a~ - Add new bookmark +- ~C-c C-b d~ - Delete bookmark +- ~C-c C-b l~ - List all bookmarks +- ~C-c C-b e~ - Edit bookmark description +- ~C-c C-b r~ - Reload bookmarks from file +- ~C-c C-b i~ - Initialize empty bookmark file ** Basic workflow @@ -121,11 +144,6 @@ All functions can also be called via ~M-x~: 2. ~M-x esb-add-bookmark~ - Add your first bookmark 3. Commit and push to GitHub -*** Daily usage -1. ~C-c b s~ - Quick bookmark selection -2. ~C-c b a~ - Add new bookmarks -3. Periodically commit and push changes - *** Syncing across machines #+BEGIN_SRC bash # Pull latest bookmarks @@ -136,7 +154,7 @@ M-x esb-reload-bookmarks # After making changes: commit and push git add bookmarks.gpg -git commit -m "Update bookmarks" +git commit -m "your message" git push #+END_SRC @@ -146,7 +164,7 @@ git push #+BEGIN_SRC bash # After adding bookmarks in Emacs git add bookmarks.gpg -git commit -m "Add new bookmarks" +git commit -m "add new bookmarks, etc..." git push #+END_SRC @@ -177,8 +195,6 @@ Note: GPG files can't be automatically merged, so avoid simultaneous edits when - Never commit your GPG private key to the repository - Regularly backup your GPG keys! -* Troubleshooting - * Configuration Options ** Customizable Variables @@ -209,6 +225,19 @@ The encrypted file is just a simple JSON array: ] #+END_SRC +* 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 + * 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. diff --git a/esb.el b/esb.el index 578cd0e..48f42ff 100644 --- a/esb.el +++ b/esb.el @@ -84,6 +84,7 @@ ;;; Interactive functions +;;;###autoload (defun esb-add-bookmark (url &optional description) "Add a new bookmark with URL and optional DESCRIPTION." (interactive "sBookmark URL: \nsDescription (optional): ") @@ -98,6 +99,7 @@ (esb--save-if-dirty) (message "Added bookmark: %s" url))))) +;;;###autoload (defun esb-delete-bookmark () "Delete a bookmark by selecting from list." (interactive) @@ -114,6 +116,7 @@ (esb--save-if-dirty) (message "Deleted bookmark: %s" selected-url))))) +;;;###autoload (defun esb-list-bookmarks () "Display all bookmarks in a buffer." (interactive) @@ -130,6 +133,7 @@ (princ (format " %s\n" desc))) (princ "\n"))))))) +;;;###autoload (defun esb-select-bookmark () "Select a bookmark and copy URL to clipboard." (interactive) @@ -140,6 +144,7 @@ (kill-new selected-url) (message "Copied to clipboard: %s" selected-url))))) +;;;###autoload (defun esb-edit-bookmark () "Edit description of an existing bookmark." (interactive) @@ -156,6 +161,7 @@ (esb--save-if-dirty) (message "Updated bookmark: %s" selected-url))))) +;;;###autoload (defun esb-reload-bookmarks () "Reload bookmarks from file (useful after git pull)." (interactive) @@ -164,6 +170,7 @@ (esb--get-bookmarks) (message "Bookmarks reloaded from %s" esb-bookmarks-file)) +;;;###autoload (defun esb-initialize () "Initialize bookmark file if it doesn't exist." (interactive) @@ -172,24 +179,15 @@ (esb--write-bookmarks '()) (message "Initialized empty bookmark file at: %s" esb-bookmarks-file))) -;;; Key bindings -(defvar esb-mode-map - (let ((map (make-sparse-keymap))) - (define-key map (kbd "C-c b s") 'esb-select-bookmark) - (define-key map (kbd "C-c b a") 'esb-add-bookmark) - (define-key map (kbd "C-c b d") 'esb-delete-bookmark) - (define-key map (kbd "C-c b l") 'esb-list-bookmarks) - (define-key map (kbd "C-c b e") 'esb-edit-bookmark) - (define-key map (kbd "C-c b r") 'esb-reload-bookmarks) - (define-key map (kbd "C-c b i") 'esb-initialize) - map) - "Keymap for esb bookmark commands.") +;;;###autoload (define-minor-mode esb-mode - "Minor mode for encrypted bookmark management." + "Minor mode for encrypted bookmark management. +This mode provides no key bindings by default. +Users should define their own key bindings for ESB functions." :global t - :keymap esb-mode-map) + :group 'esb) (provide 'esb) -- cgit v1.3