Termux Clipboard

Integrate Vim '+' register with the Android system clipboard via Termux APIs

⬆️ Top of Document
🏗️ Requirements
⚡ Quick Start
🧰 Usage
🗒 Notes
- Clipboard not accessible on non-root device when screen is off
- Non-recursive Mappings
📈 Contributing
- 🔱 Forking
📇 Attribution
⚖️ Licensing

Requirements

This repository requires the [Vim][vim_home] text editor to be installed the source code is available on GitHub -- vim/vim, and most GNU Linux package managers are able to install Vim directly, eg...

Termux
```
pkg install termux-api
```

Note; installing without python support, eg. pkg install vim, should also function fine instead for this plugin

Additionally the Termux API CLI must be installed within via;

pkg install termux-api

... As well as the corresponding API

Quick Start

Clone this project...

Termux

mkdir -vp ~/git/hub/vim-utilities

cd ~/git/hub/vim-utilities

git clone git@github.com:vim-utilities/termux-clipboard.git

This repository is a Vim plugin, and can be installed by cloning to your plugin directory, eg...

mkdir ~/.vim/plugin
cd ~/.vim/plugin
git clone git@github.com:vim-utilities/termux-clipboard.git

... or if cloned elsewhere, then symbolically link to your plugin directory...

ln -s "${HOME}/git/hub/vim-utilities/termux-clipboard"\
      "${HOME}/.vim/plugin/"

Usage

Just use "+y, "+p, <C-R>+, and friends as you always do. Specifically, here's what's supported:

Any yank command that starts with "+ (e.g. "+yy or "+yiw) in insert and visual modes.
Pasting in normal and visual modes with "+p or "+P.
Pasting in insert mode with <C-R>+, <C-R><C-R>+, <C-R><C-O>+, or <C-R><C-P>+.
Yanking and pasting (p and P in normal and visual modes) with clipboard=unnamedplus.

If you need more functionality, consider checking out vim-fakeclip.

Notes

This repository may not be feature complete and/or fully functional, Pull Requests that add features or fix bugs are certainly welcomed.

Clipboard not accessible on non-root device when screen is off

⚠️ Certain security choices of Android 10, related to accessibility abuses and installation methods, it is not possible to yank/put from/to the system clipboard when the device's screen is off! And may not be possible if the Termux application is not in the foreground.

For those using SSH the current best non-root workaround currently is to keep the screen on and unlocked, and Termux in the foreground.

Non-recursive Mappings

This plugin uses mappings of "+p, <C-R>+, "+, etc. to do its job. As a result, it won't work with existing non-recursive mappings that run these commands, e.g. nnoremap <Leader>p "+p. If you have mappings like these, you'll need to use their recursive counterparts instead for the plugin to work.

Contributing

Options for contributing to termux-clipboard and vim-utilities

Forking

Start making a Fork of this repository to an account that you have write permissions for.

Add remote for fork URL. The URL syntax is git@github.com:<NAME>/<REPO>.git...

cd ~/git/hub/vim-utilities/termux-clipboard

git remote add fork git@github.com:<NAME>/termux-clipboard.git

Commit your changes and push to your fork, eg. to fix an issue...

cd ~/git/hub/vim-utilities/termux-clipboard


git commit -F- <<'EOF'
:bug: Fixes #42 Issue


**Edits**


- `<SCRIPT-NAME>` script, fixes some bug reported in issue
EOF


git push fork main

Note, the -u option may be used to set fork as the default remote, eg. git push -u fork main however, this will also default the fork remote for pulling from too! Meaning that pulling updates from origin must be done explicitly, eg. git pull origin main

Then on GitHub submit a Pull Request through the Web-UI, the URL syntax is https://github.com/<NAME>/<REPO>/pull/new/<BRANCH>

Note; to decrease the chances of your Pull Request needing modifications before being accepted, please check the dot-github repository for detailed contributing guidelines.

Attribution

License

The MIT License (MIT)

Copyright (c) 2021 Jason Cox
Copyright (C) 2024 S0AndS0

Permission is hereby granted, free of charge, to any person obtaining a copy
of this software and associated documentation files (the "Software"), to deal
in the Software without restriction, including without limitation the rights
to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
copies of the Software, and to permit persons to whom the Software is
furnished to do so, subject to the following conditions:

The above copyright notice and this permission notice shall be included in all
copies or substantial portions of the Software.

THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
SOFTWARE.

For further details review full length version of MIT License.