1 unstable release
0.0.0 | Jan 18, 2024 |
---|
#4 in #clipboard-history
2KB
Ringboard
Ringboard is a fast, efficient, and composable clipboard manager for Linux.
Basic features:
- Ringboard remembers what you've copied across reboots.
- Ringboard can save anything, including images or arbitrary bytes.
- Your clipboard history is searchable with either Regex or raw queries.
- Ringboard can be installed anywhere (on Linux) and has no ties to a specific desktop environment or framework.
Differentiators:
- Ringboard is efficient: it uses a custom binary format to save space on disk, io_uring to avoid allocations and be fast with just a single thread, and mmap to require minimal working set memory.
- Ringboard is fast and scalable: it was architected to load only the data needed, when needed. For example, displaying the last 100 most recent clipboard entries requires loading just those 100 entries. Ringboard can support up to ~1 million saved clipboard entries. If you copied 100 things every day, it would still take almost 30 years before old entries are overwritten.
- Ringboard is composable: it uses a client server architecture to support any app modifying or reading data. For example, you can add data via a CLI or an X11 or Wayland clipboard watcher. Different GUIs can each display the clipboard as they wish, enabling deep integration with desktop environments.
A detailed technical breakdown of the project is available at https://alexsaveau.dev/blog/ringboard.
Demo
Installation instructions
Note: Ringboard is Linux-only and requires a relatively recent Kernel (6+).
The easiest way to get going is to install cargo with nightly and then run the installation script for systemd:
rustup install nightly # If not already installed
curl -s https://raw.githubusercontent.com/SUPERCILEX/clipboard-history/master/install-with-cargo-systemd.sh | bash
Additionally, consider using https://github.com/nabijaczleweli/cargo-update to update your cargo apps.
Manual installation
Common core
You'll need the server, an X11 or Wayland clipboard watcher, and a way to view your clipboard:
- Install the server from source with
cargo install clipboard-history-server --no-default-features --features systemd
or download a prebuilt binary. - Determine whether you are using Wayland or X11 with
bash -c 'echo $XDG_SESSION_TYPE'
:- If on Wayland, install from source with
cargo install clipboard-history-wayland --no-default-features
(prebuild binaries are also available as before). - If on X11, install from source with
cargo install clipboard-history-x11 --no-default-features
.
- If on Wayland, install from source with
- Install a client of your choice:
- egui:
cargo install clipboard-history-egui --no-default-features --features wayland/x11
- ratatui:
cargo install clipboard-history-tui
- CLI:
cargo install clipboard-history
- egui:
- Add a
custom shortcut
to start your GUI. See the
egui
docs for example.
For systemd
Install the server and X11 or
Wayland services into ~/.config/systemd/user
and enable them:
systemctl --user enable ringboard-{wayland,x11}
.
For framework-less systems
You'll need to start the Ringboard server and X11/Wayland clipboard watcher on boot.
Migrating from existing clipboard managers
Tooling is provided to migrate from other clipboard managers. Run:
$ ringboard migrate gch
to import your Gnome Clipboard History entries.$ ringboard migrate g-paste
to import your GPaste history.$ ringboard migrate clipboard-indicator
to import your Clipboard Indicator history.
Project breakdown
Each submodule contains its own README with details on the submodule.
/
cli/
: The Ringboard Command Line Interface contains tools for working with the Ringboard database.client-sdk/
: The client SDK offers APIs to read and write Ringboard data.core/
: The core code shared across many Ringboard crates.egui/
: The egui Ringboard client displays clipboard entries in a standard GUI.server/
: The Ringboard server writes data to the Ringboard database.tui/
: The ratatui Ringboard client displays clipboard entries in your terminal.wayland/
: The Wayland clipboard watcher sends new clipboard entries to the Ringboard server.x11/
: The X11 clipboard watcher sends new clipboard entries to the Ringboard server.