README.md (3228B)
1 [![Tests](https://img.shields.io/travis/cdown/clipmenu/develop.svg)](https://travis-ci.org/cdown/clipmenu) 2 3 clipmenu is a simple clipboard manager using [dmenu][] (or [rofi][] with 4 `CM_LAUNCHER=rofi`) and [xsel][]. 5 6 # Demo 7 8 ![Demo](https://cloud.githubusercontent.com/assets/660663/24079784/6f76da94-0c88-11e7-8251-40b1f02ebf3c.gif) 9 10 # Usage 11 12 Start `clipmenud`, then run `clipmenu` to select something to put on the 13 clipboard. For systemd users, a user service called `clipmenud` is packaged as 14 part of the project. 15 16 You may wish to bind a shortcut in your window manager to launch `clipmenu`. 17 18 All args passed to clipmenu are transparently dispatched to dmenu. That is, if 19 you usually call dmenu with args to set colours and other properties, you can 20 invoke clipmenu in exactly the same way to get the same effect, like so: 21 22 clipmenu -i -fn Terminus:size=8 -nb '#002b36' -nf '#839496' -sb '#073642' -sf '#93a1a1' 23 24 For a full list of environment variables that clipmenud can take, please see 25 `clipmenud --help`. 26 27 # Features 28 29 The behavior of `clipmenud` can be customized through environment variables. 30 Despite being only <300 lines, clipmenu has many useful features, including: 31 32 * Customising the maximum number of clips stored (default 1000) 33 * Disabling clip collection temporarily with `clipctl disable`, reenabling with 34 `clipctl enable` 35 * Not storing clipboard changes from certain applications, like password 36 managers 37 * Taking direct ownership of the clipboard 38 * ...and much more. 39 40 Check `clipmenud --help` to view all possible environment variables and what 41 they do. If you manage `clipmenud` with `systemd`, you can override the 42 defaults by using `systemctl --user edit clipmenud` to generate an override 43 file. 44 45 # Supported launchers 46 47 Any dmenu-compliant application will work, but here are `CM_LAUNCHER` 48 configurations that are known to work: 49 50 - `dmenu` (the default) 51 - `fzf` 52 - `rofi` 53 - `rofi-script`, for [rofi's script 54 mode](https://github.com/davatorium/rofi-scripts/tree/master/mode-scripts) 55 56 # Installation 57 58 Several distributions, including Arch and Nix, provide clipmenu as an official 59 package called `clipmenu`. 60 61 ## Manual installation 62 63 If your distribution doesn't provide a package, you can manually install using 64 `make install` (or better yet, create a package for your distribution!). You 65 will need `xsel` and `clipnotify` installed, and also `dmenu` unless you plan 66 to use a different launcher. 67 68 # How does it work? 69 70 clipmenud is less than 300 lines, and clipmenu is less than 100, so hopefully 71 it should be fairly self-explanatory. However, at the most basic level: 72 73 ## clipmenud 74 75 1. `clipmenud` uses [clipnotify](https://github.com/cdown/clipnotify) to wait 76 for new clipboard events. 77 2. If `clipmenud` detects changes to the clipboard contents, it writes them out 78 to the cache directory and an index using a hash as the filename. 79 80 ## clipmenu 81 82 1. `clipmenu` reads the index to find all available clips. 83 2. `dmenu` is executed to allow the user to select a clip. 84 3. After selection, the clip is put onto the PRIMARY and CLIPBOARD X 85 selections. 86 87 [dmenu]: http://tools.suckless.org/dmenu/ 88 [rofi]: https://github.com/DaveDavenport/Rofi 89 [xsel]: http://www.vergenet.net/~conrad/software/xsel/