{"id":26847719,"url":"https://github.com/open-technology-foundation/clip","last_synced_at":"2026-05-10T02:34:47.358Z","repository":{"id":284868502,"uuid":"956322459","full_name":"Open-Technology-Foundation/clip","owner":"Open-Technology-Foundation","description":"Tool for clipboard operations in Linux. Easily copy file contents to clipboard or paste clipboard contents to files or stdout.","archived":false,"fork":false,"pushed_at":"2025-03-28T04:08:27.000Z","size":15,"stargazers_count":0,"open_issues_count":0,"forks_count":0,"subscribers_count":1,"default_branch":"main","last_synced_at":"2025-03-28T05:19:48.649Z","etag":null,"topics":["bash","clipboard","linux"],"latest_commit_sha":null,"homepage":"https://yatti.id/","language":"Shell","has_issues":true,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":null,"license":"gpl-3.0","status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/Open-Technology-Foundation.png","metadata":{"files":{"readme":"README.md","changelog":null,"contributing":null,"funding":null,"license":"LICENSE","code_of_conduct":null,"threat_model":null,"audit":null,"citation":null,"codeowners":null,"security":null,"support":null,"governance":null,"roadmap":null,"authors":null,"dei":null,"publiccode":null,"codemeta":null}},"created_at":"2025-03-28T04:02:51.000Z","updated_at":"2025-03-28T04:10:20.000Z","dependencies_parsed_at":"2025-03-28T05:29:53.547Z","dependency_job_id":null,"html_url":"https://github.com/Open-Technology-Foundation/clip","commit_stats":null,"previous_names":["open-technology-foundation/clip"],"tags_count":0,"template":false,"template_full_name":null,"repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/Open-Technology-Foundation%2Fclip","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/Open-Technology-Foundation%2Fclip/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/Open-Technology-Foundation%2Fclip/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/Open-Technology-Foundation%2Fclip/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/Open-Technology-Foundation","download_url":"https://codeload.github.com/Open-Technology-Foundation/clip/tar.gz/refs/heads/main","host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":246374710,"owners_count":20766944,"icon_url":"https://github.com/github.png","version":null,"created_at":"2022-05-30T11:31:42.601Z","updated_at":"2022-07-04T15:15:14.044Z","host_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub","repositories_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories","repository_names_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repository_names","owners_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners"}},"keywords":["bash","clipboard","linux"],"created_at":"2025-03-30T20:23:34.976Z","updated_at":"2026-05-10T02:34:47.348Z","avatar_url":"https://github.com/Open-Technology-Foundation.png","language":"Shell","funding_links":[],"categories":[],"sub_categories":[],"readme":"# clip\n\n[![Version](https://img.shields.io/badge/version-1.0.1-blue.svg)](https://github.com/Open-Technology-Foundation/clip)\n[![License](https://img.shields.io/badge/license-GPL--3.0-green.svg)](LICENSE)\n[![Bash](https://img.shields.io/badge/bash-5.2%2B-orange.svg)](https://www.gnu.org/software/bash/)\n[![BCS Compliant](https://img.shields.io/badge/BCS-100%25-brightgreen.svg)](https://github.com/Open-Technology-Foundation/bash-coding-standard)\n[![ShellCheck](https://img.shields.io/badge/shellcheck-clean-success.svg)](https://www.shellcheck.net/)\n[![Tests](https://img.shields.io/badge/tests-97.4%25%20pass-success.svg)](#testing)\n[![Security](https://img.shields.io/badge/security-0%20vulnerabilities-brightgreen.svg)](#security)\n\nA professional-grade command-line clipboard utility for Linux systems that enables seamless data transfer between terminal and GUI applications. Fully BCS-compliant with comprehensive input validation and zero security vulnerabilities.\n\n## Quick Install\n\n**One-liner** (downloads and installs automatically):\n```bash\ncurl -sSL https://raw.githubusercontent.com/Open-Technology-Foundation/clip/main/install.sh | bash\n```\n\n**Or clone and install using make**:\n```bash\ngit clone https://github.com/Open-Technology-Foundation/clip.git\ncd clip\nsudo make install      # System-wide installation\n```\n\n**User-level install** (no sudo required):\n```bash\ngit clone https://github.com/Open-Technology-Foundation/clip.git\ncd clip\n./install.sh           # Choose option 1 for ~/.local/bin\n```\n\nFor detailed installation options and manual installation, see [Installation](#installation).\n\n## Table of Contents\n\n- [Features](#features)\n- [Code Quality](#code-quality)\n- [Requirements](#requirements)\n- [Installation](#installation)\n- [Usage](#usage)\n  - [Basic Operations](#basic-operations)\n  - [Image Operations](#image-operations)\n  - [Advanced Features](#advanced-features)\n- [Examples](#examples)\n- [Testing](#testing)\n- [Project Structure](#project-structure)\n- [Troubleshooting](#troubleshooting)\n- [Development](#development)\n- [Contributing](#contributing)\n- [License](#license)\n\n## Features\n\n- ✓ **Text Operations**: Copy single or multiple files to clipboard, paste with formatting preservation\n- ✓ **PNG Image Support**: Intelligent image handling with clipboard detection\n- ✓ **Smart Compression**: Two modes with automatic tool selection:\n  - **Optimize mode**: pngquant (best) → optipng → imagemagick (fallback)\n  - **Resize mode**: Dimension-based compression via ImageMagick\n- ✓ **Intelligent Size Checking**: Only uses compressed version if actually smaller\n- ✓ **Auto-Installation**: Prompts for missing compression tools with user confirmation\n- ✓ **Flexible Output**: Paste to stdout or files with automatic directory creation\n- ✓ **Custom Formatting**: Add headers/footers when copying files (markdown, XML, etc.)\n- ✓ **Bash 5.2+ Modern Patterns**: `[[`, `(())`, proper arrays, `${var@Q}` quoting\n- ✓ **Professional Error Handling**: `set -euo pipefail`, comprehensive input validation\n- ✓ **Safe Reinstallation**: Automatically replaces existing installations without prompts\n- ✓ **Verbose/Quiet Modes**: Control output verbosity for scripting or debugging\n\n## Code Quality\n\nThis project maintains professional-grade code standards:\n\n- ✓ **BCS Compliance**: 100% compliant with Bash Coding Standard\n- ✓ **ShellCheck Clean**: Zero warnings or errors on all scripts\n- ✓ **Security**: Zero vulnerabilities detected\n  - No command injection risks\n  - Safe file operations with validation\n  - Proper input sanitization\n  - Protected variable expansions\n- ✓ **Test Coverage**: 97.4% pass rate (76/78 tests)\n- ✓ **Modern Bash**: Bash 5.2+ patterns throughout\n  - `[[` for conditionals (not `[` or `test`)\n  - `(())` for arithmetic (not `expr`)\n  - Proper array handling with `\"${array[@]}\"`\n  - No deprecated patterns (backticks, `function` keyword, etc.)\n- ✓ **Error Handling**: Comprehensive exit codes and error messages\n- ✓ **Documentation**: Inline comments explaining WHY, not just WHAT\n\n## Requirements\n\n### System Requirements\n\n- **Operating System**: Linux (X11 or Wayland with XWayland)\n- **Bash Version**: 5.2 or later\n- **Package Manager**: apt (Debian/Ubuntu) for auto-installation\n  - Manual installation supported for other distros\n\n### Display Environment\n\n- **X11**: Native support via `DISPLAY` variable\n- **Wayland**: Works via XWayland compatibility layer\n- **SSH**: X11 forwarding supported (`ssh -X`)\n\n### Dependencies\n\n**Required**:\n- `xclip` - Core clipboard operations\n\n**Optional** (for PNG compression):\n- `pngquant` - Best lossy compression with quality control\n- `optipng` - Lossless optimization (fallback)\n- `imagemagick` - Resize-based compression and final fallback\n\nAll optional dependencies can be auto-installed when needed.\n\n## Installation\n\n### Recommended: Using Makefile\n\nThe easiest and most reliable installation method.\n\n**System-wide installation** (requires sudo):\n```bash\ngit clone https://github.com/Open-Technology-Foundation/clip.git\ncd clip\nsudo make install\n```\n\nThis installs:\n- Binary to `/usr/local/bin/clip`\n- Man page to `/usr/local/share/man/man1/clip.1`\n- Bash completion to `/etc/bash_completion.d/clip` (if directory exists)\n\n**User-level installation** (no sudo required):\n\nUse the interactive install script:\n```bash\ngit clone https://github.com/Open-Technology-Foundation/clip.git\ncd clip\n./install.sh           # Choose option 1 for user-level install\n```\n\nThis installs:\n- Binary to `~/.local/bin/clip`\n- Bash completion to `~/.local/share/bash-completion/completions/clip`\n- Man page to `~/.local/share/man/man1/clip.1.gz`\n- Automatically adds `~/.local/bin` to PATH in `~/.bashrc`\n- Adds `~/.local/share/man` to MANPATH in `~/.bashrc`\n- Sets up bash completion in `~/.bashrc`\n\n**Other Makefile targets**:\n```bash\nmake help           # Show all available targets\nmake uninstall      # Remove system-wide installation\nmake test           # Run test suite\nmake check          # Verify clip is in PATH\n```\n\n### Using install.sh Script\n\nInteractive installation with auto-detection:\n\n**Local installation**:\n```bash\ngit clone https://github.com/Open-Technology-Foundation/clip.git\ncd clip\n./install.sh\n```\n\n**Remote one-liner**:\n```bash\ncurl -sSL https://raw.githubusercontent.com/Open-Technology-Foundation/clip/main/install.sh | bash\n```\n\nThe script will:\n- ✓ Auto-detect system vs user installation\n- ✓ Install dependencies (xclip) if needed\n- ✓ Set up bash completion automatically\n- ✓ Install man page with gzip compression\n- ✓ Add to PATH and MANPATH if needed (user install)\n- ✓ Verify installation\n\n**Note**: Both Makefile and install.sh automatically remove any existing clip installation (including symlinks) before installing. No prompts are given - existing files are safely replaced.\n\n### Manual Installation\n\nFor custom setups or other distributions.\n\n**1. Download the script**:\n```bash\ngit clone https://github.com/Open-Technology-Foundation/clip.git\ncd clip\nchmod +x clip\n```\n\n**2. Install binary**:\n```bash\n# System-wide\nsudo cp clip /usr/local/bin/\n\n# User-level\nmkdir -p ~/.local/bin\ncp clip ~/.local/bin/\nexport PATH=\"$HOME/.local/bin:$PATH\"  # Add to ~/.bashrc for persistence\n```\n\n**3. Install bash completion** (optional):\n```bash\n# System-wide\nsudo mkdir -p /usr/local/share/bash-completion/completions\nsudo cp clip.bash_completion /usr/local/share/bash-completion/completions/clip\n\n# User-level\nmkdir -p ~/.local/share/bash-completion/completions\ncp clip.bash_completion ~/.local/share/bash-completion/completions/clip\necho '[ -f ~/.local/share/bash-completion/completions/clip ] \u0026\u0026 source ~/.local/share/bash-completion/completions/clip' \u003e\u003e ~/.bashrc\n```\n\n**4. Verify installation**:\n```bash\nclip -V                    # Should show: clip 1.0.1\nclip -h                    # Show help text\nman clip                   # View manual page\n```\n\n### Uninstallation\n\n**Using Makefile** (system-wide only):\n```bash\nsudo make uninstall\n```\n\n**Manual removal**:\n```bash\n# System-wide\nsudo rm /usr/local/bin/clip\nsudo rm /usr/local/share/bash-completion/completions/clip\n\n# User-level\nrm ~/.local/bin/clip\nrm ~/.local/share/bash-completion/completions/clip\n# Also remove entries from ~/.bashrc\n```\n\n## Usage\n\nFor complete documentation, see: `man clip`\n\n### Basic Operations\n\n**Copy file to clipboard**:\n```bash\nclip filename.txt\n```\n\n**Copy multiple files** (concatenated):\n```bash\nclip file1.txt file2.txt file3.txt\n```\n\n**Paste clipboard to stdout**:\n```bash\nclip -p\n```\n\n**Paste clipboard to file**:\n```bash\nclip -p output.txt\n```\n\n**Quiet mode** (for scripts):\n```bash\nclip -q important.txt\n```\n\n### Image Operations\n\n**Paste PNG image**:\n```bash\nclip -p screenshot.png\n```\n\n**Paste with optimization** (automatic tool selection):\n```bash\nclip -p -c optimized.png\n```\n\n**Paste with quality control** (pngquant):\n```bash\nclip -p -c -Q 85 image.png    # Max quality 85 (lower = smaller)\n```\n\n**Resize-based compression** (ImageMagick):\n```bash\nclip -p -r -Q 75 thumbnail.png    # Resize to 75% of dimensions\nclip -p -r -Q 50 small.png        # Resize to 50% of dimensions\n```\n\n### Advanced Features\n\n**Copy with custom headers/footers**:\n```bash\n# Markdown code blocks\nclip script.sh -f -H '```bash\\n' -F '\\n```\\n'\n\n# XML format\nclip data.txt -f -H '\u003cfile name=\"{}\"\u003e\u003c![CDATA[\\n' -F ']]\u003e\u003c/file\u003e\\n'\n\n# SQL comments\nclip query.sql -f -H '-- Query: {}\\n' -F '\\n-- End\\n'\n```\n\n**Multiple files with headers**:\n```bash\nclip intro.md features.md api.md -f\n```\n\n### Command-Line Options\n\n| Short | Long | Description |\n|-------|------|-------------|\n| `-p` | `--paste` | Paste mode (default is copy) |\n| `-c` | `--compress` | Optimize PNG (pngquant/optipng/imagemagick) |\n| `-r` | `--resize` | Use resize-based compression |\n| `-Q N` | `--quality N` | Compression quality 1-100 (default: 90) |\n| `-f` | `--use-file-header` | Add headers/footers when copying |\n| `-H STR` | `--file-header STR` | Custom header (use {} for filename) |\n| `-F STR` | `--file-footer STR` | Custom footer |\n| `-v` | `--verbose` | Verbose output (default) |\n| `-q` | `--quiet` | Quiet mode (suppress info/success messages) |\n| `-V` | `--version` | Display version |\n| `-h` | `--help` | Display help message |\n\n**Combined short options** are supported:\n```bash\nclip -vp          # Verbose paste\nclip -qc          # Quiet compress\nclip -pc -Q 85    # Paste, compress, quality 85\n```\n\n## Examples\n\n### Text Workflows\n\n**Copy configuration files**:\n```bash\nclip ~/.bashrc\nclip /etc/nginx/nginx.conf\n```\n\n**Pipe command output via clipboard**:\n```bash\n# Copy output to clipboard\nls -la | xclip -selection clipboard\n# Paste to file\nclip -p directory-listing.txt\n```\n\n**Copy with formatting for documentation**:\n```bash\n# Create markdown code block\nclip myfunction.py -f -H '```python\\n' -F '\\n```\\n'\n\n# Copy multiple files with separators\nclip *.py -f -H '\\n# File: {}\\n' -F '\\n---\\n'\n```\n\n### Image Workflows\n\n**Screenshot → Optimize → Save**:\n```bash\n# 1. Take screenshot (copies to clipboard)\ngnome-screenshot -a\n\n# 2. Paste and optimize\nclip -p -c screenshot.png\n```\n\n**Test different compression settings**:\n```bash\n# Try multiple quality levels\nfor q in 60 70 80 90; do\n  clip -p -c -Q $q \"screenshot_q${q}.png\"\ndone\n```\n\n**Convert via clipboard**:\n```bash\n# Put image in clipboard\nxclip -selection clipboard -t image/png \u003c input.png\n\n# Output with different compressions\nclip -p -c optimized.png              # Optimize (best tool)\nclip -p -r -Q 75 resized_75.png       # Resize to 75%\nclip -p -r -Q 50 thumbnail.png        # Resize to 50%\n```\n\n### Scripting Integration\n\n**Silent operation with error checking**:\n```bash\n#!/bin/bash\nif clip -q important.txt; then\n  echo '✓ Copied to clipboard'\nelse\n  echo '✗ Copy failed' \u003e\u00262\n  exit 1\nfi\n```\n\n**Pipeline processing**:\n```bash\n# Filter clipboard content\nclip -p | grep ERROR | wc -l\n\n# Process and save\nclip -p | sed 's/old/new/g' \u003e processed.txt\n\n# Combine with other tools\nclip -p | jq . \u003e formatted.json\n```\n\n**Conditional operations**:\n```bash\n# Only copy if file exists and is readable\n[[ -r file.txt ]] \u0026\u0026 clip file.txt || echo \"Cannot read file\"\n\n# Copy and backup\nclip config.json \u0026\u0026 cp config.json config.json.bak\n```\n\n### Development Tasks\n\n**Quick code review**:\n```bash\n# Copy all changed files\nclip $(git diff --name-only)\n\n# Copy specific function\nclip -f main.py -H '# Function: main()\\n' -F '\\n'\n```\n\n**Documentation generation**:\n```bash\n# Combine docs for review\nclip README.md API.md INSTALL.md -f\n\n# Add timestamped header\nclip error.log -f -H \"# Captured: $(date)\\n\"\n```\n\n**Batch operations**:\n```bash\n# Copy all test files\nclip tests/*.py -f -H '\\n## {}\\n' -F ''\n\n# Quick file comparison\nclip file1.txt file2.txt -f\n```\n\n## Testing\n\nThe project includes a comprehensive test suite with 9 test scripts covering all functionality.\n\n### Running Tests\n\n```bash\n# Run all tests (default)\n./tests/run_tests.sh\n\n# Run specific test categories\n./tests/run_tests.sh -b    # Basic functionality\n./tests/run_tests.sh -t    # Text operations\n./tests/run_tests.sh -i    # Image handling\n./tests/run_tests.sh -c    # Compression\n./tests/run_tests.sh -e    # Error handling\n\n# Combine categories\n./tests/run_tests.sh -t -i -c\n\n# Verbose output\n./tests/run_tests.sh -v\n```\n\n### Test Results\n\nCurrent test status: **97.4% pass rate** (76/78 tests passed, 2 skipped)\n\nTest output uses standardized icons:\n- ✓ **Pass**: Test succeeded\n- ✗ **Fail**: Test failed\n- ⊘ **Skip**: Test skipped (missing dependencies or environment)\n- ℹ **Info**: Informational message\n\n### Test Categories\n\n**Basic Tests** (`test_basic.sh`):\n- ✓ Help and version display\n- ✓ Option parsing (short, long, combined)\n- ✓ Invalid option handling\n- ✓ GUI environment detection\n\n**Text Tests** (`test_text.sh`):\n- ✓ Single/multiple file copying\n- ✓ Custom headers and footers\n- ✓ Empty files and large files\n- ✓ Special characters preservation\n- ✓ Clipboard content validation\n\n**Image Tests** (`test_images.sh`):\n- ✓ PNG clipboard detection\n- ✓ Image paste operations\n- ✓ JPEG fixture availability\n- ✓ Compression option validation\n\n**Compression Tests** (`test_compression.sh`):\n- ✓ pngquant optimization (quality levels 20-100)\n- ✓ optipng optimization\n- ✓ Resize operations (10%-100%)\n- ✓ File size comparisons\n- ✓ Fallback behavior\n\n**Error Tests** (`test_errors.sh`):\n- ✓ Invalid options\n- ✓ Missing files\n- ✓ Permission checks\n- ✓ Dependency validation\n\n### Code Quality Verification\n\n```bash\n# Run ShellCheck on all scripts\nshellcheck -x clip\nfind tests -name \"*.sh\" -exec shellcheck -x {} \\;\n\n# Verify BCS compliance (if bcs tool available)\nbcs check clip\n\n# Check version consistency\n./clip -V\ngrep \"VERSION=\" clip\n```\n\n## Project Structure\n\n```\nclip/\n├── clip                    # Main script (393 lines, 15 functions)\n├── clip.1                  # Man page (groff format)\n├── clip.bash_completion    # Bash tab completion (92 lines)\n├── install.sh              # Installation script (334 lines)\n├── Makefile                # Installation targets\n├── README.md               # This documentation\n├── LICENSE                 # GPL-3.0 license\n└── tests/                  # Test suite (97.4% pass rate)\n    ├── fixtures/           # Test data (PNG, JPEG samples)\n    ├── test_lib.sh         # Test framework (260 lines)\n    ├── run_tests.sh        # Main test runner\n    ├── test_basic.sh       # Basic functionality tests\n    ├── test_text.sh        # Text operation tests\n    ├── test_images.sh      # Image handling tests\n    ├── test_compression.sh # Compression tests\n    ├── test_errors.sh      # Error handling tests\n    ├── test_simple.sh      # Quick smoke tests\n    └── test_summary.sh     # Test summary reporter\n```\n\n### Key Components\n\n**Main Script** (`clip`):\n- 393 lines of BCS-compliant Bash 5.2+ code\n- 15 functions with comprehensive documentation\n- Zero ShellCheck warnings\n- Complete error handling with `set -euo pipefail`\n\n**Test Framework** (`test_lib.sh`):\n- 6 assertion functions\n- Color-coded output\n- Automatic setup/cleanup\n- Dependency checking\n\n## Exit Codes\n\n| Code | Name | Meaning |\n|------|------|---------|\n| 0 | SUCCESS | Successful operation |\n| 1 | ERR_GENERAL | General error (user aborted, clipboard operation failed) |\n| 5 | ERR_IO | I/O error (cannot create file or directory) |\n| 8 | ERR_REQUIRED | Required argument missing (no files given, option needs value) |\n| 18 | ERR_NODEP | Missing dependency (xclip, pngquant, etc.) |\n| 19 | ERR_ENV | Environment error (no GUI display detected) |\n| 22 | ERR_INVAL | Invalid argument (unknown option, value out of range) |\n\n## Troubleshooting\n\n### ◉ Clipboard Not Working\n\n**Check display environment**:\n```bash\necho $DISPLAY          # Should show :0 or similar\necho $WAYLAND_DISPLAY  # May show wayland-0\n```\n\n**For SSH sessions**, enable X11 forwarding:\n```bash\nssh -X user@host\n```\n\n### ◉ xclip Not Installed\n\nThe script requires xclip and will exit with an error if not found:\n```bash\nclip myfile.txt\n# ✗ xclip is required but not installed. Please run: sudo apt install xclip\n```\n\nInstall manually:\n```bash\nsudo apt update \u0026\u0026 sudo apt install xclip\n```\n\n### ◉ Image Compression Not Working\n\n**Check available tools**:\n```bash\nwhich pngquant optipng convert\n```\n\n**Install compression tools**:\n```bash\n# Best option: all tools\nsudo apt install pngquant optipng imagemagick\n\n# Minimum for optimization\nsudo apt install pngquant\n\n# Minimum for resize mode\nsudo apt install imagemagick\n```\n\n### ▲ Permission Denied\n\n**Make script executable**:\n```bash\nchmod +x clip\n```\n\n**Check file permissions**:\n```bash\nls -l clip    # Should show -rwxr-xr-x or similar\n```\n\n### ▲ Compression Doesn't Reduce Size\n\nThis is normal behavior. The script only uses the compressed version if it's actually smaller:\n\n```bash\nclip -p -c image.png\n# ◉ Original image size: 500000 bytes\n# ◉ Compressed image size: 520000 bytes\n# ◉ Compression did not reduce file size, using original\n```\n\nSome images (already compressed, small, or simple) may not compress further.\n\n### ◉ Large File Handling\n\nFor very large files, use quiet mode to reduce overhead:\n```bash\nclip -q largefile.txt\n```\n\nConsider splitting extremely large files:\n```bash\nsplit -b 10M largefile.txt part_\nclip part_* -f\n```\n\n### ◉ Wayland Compatibility\n\nWayland systems work via XWayland compatibility:\n```bash\n# Both should be set on Wayland\necho $WAYLAND_DISPLAY\necho $DISPLAY\n```\n\nIf `DISPLAY` is not set, xclip may not work. Ensure XWayland is running.\n\n## Performance Notes\n\n- ✓ **Compression intelligence**: Automatically skips if result would be larger\n- ✓ **Tool caching**: Command paths cached at startup, not repeatedly looked up\n- ✓ **Single-pass processing**: Multiple files processed in one pipeline\n- ✓ **Quiet mode**: Use `-q` for scripting to reduce overhead\n- ✓ **Sequential file processing**: Files handled one at a time (not parallel)\n\nTypical performance:\n- Text files: Near-instant (limited by clipboard I/O)\n- PNG optimization: 1-3 seconds for typical screenshots\n- Resize operations: \u003c1 second for most images\n\n## Limitations\n\n- **Platform**: Linux only (X11 or Wayland with XWayland)\n- **Image format**: PNG only for paste operations with compression\n- **Package manager**: Auto-install requires apt (manual install supported for others)\n- **Text encoding**: Assumes UTF-8 (most common)\n- **No clipboard history**: Single clipboard operation only\n- **No clipboard monitoring**: Manual invocation required\n\n## Development\n\n### Code Standards\n\nThis project follows strict Bash 5.2+ coding standards:\n\n**BCS Compliance** (100%):\n- Shebang: `#!/usr/bin/bash`\n- Error handling: `set -euo pipefail`\n- Required shopt: `inherit_errexit extglob nullglob`\n- 2-space indentation (no tabs)\n- `declare` with proper types (`-i` for integers, `-r` for readonly)\n- Conditionals: `[[` (not `[` or `test`)\n- Arithmetic: `(())` (not `expr` or `$[]`)\n- No deprecated patterns (backticks, `function` keyword, etc.)\n\n**Security Best Practices**:\n- No `eval` with user input\n- All variables quoted: `\"$var\"`\n- File operations validated: `[[ -f \"$file\" ]]`\n- Input bounds checking: `((QUALITY \u003e= 1 \u0026\u0026 QUALITY \u003c= 100))`\n- Safe temporary files with cleanup traps\n- Interactive confirmations for destructive operations\n\n**Documentation**:\n- Function headers explain WHY, not just WHAT\n- Complex logic has inline explanations\n- ShellCheck suppressions documented with reasons\n\n### Development Setup\n\n```bash\n# Clone repository\ngit clone https://github.com/Open-Technology-Foundation/clip.git\ncd clip\n\n# Run tests\n./tests/run_tests.sh\n\n# Check code quality\nshellcheck -x clip\nshellcheck -x tests/*.sh\n\n# Verify BCS compliance\nbcs check clip    # If bcs tool available\n```\n\n### Making Changes\n\n1. **Follow code style** - Match existing patterns\n2. **Add tests** - Cover new functionality\n3. **Run ShellCheck** - Must pass with zero warnings\n4. **Test thoroughly** - Run full test suite\n5. **Document** - Update help text and README\n\n## Contributing\n\nContributions are welcome! Please ensure all submissions meet quality standards:\n\n### Requirements for Pull Requests\n\n**✓ Code Quality**:\n- ShellCheck clean (zero warnings)\n- BCS compliant\n- Bash 5.2+ patterns only\n- Comprehensive error handling\n\n**✓ Testing**:\n- Add tests for new features\n- All existing tests must pass\n- Maintain \u003e95% pass rate\n\n**✓ Documentation**:\n- Update README.md for user-facing changes\n- Update help text in script\n- Add inline comments for complex logic\n\n**✓ Security**:\n- No command injection risks\n- Proper input validation\n- Safe file operations\n\n### Contribution Process\n\n1. **Fork** the repository\n2. **Create branch**: `git checkout -b feature/amazing-feature`\n3. **Make changes** following code standards\n4. **Test thoroughly**: `./tests/run_tests.sh \u0026\u0026 shellcheck -x clip`\n5. **Commit** with clear messages\n6. **Push**: `git push origin feature/amazing-feature`\n7. **Open Pull Request** with:\n   - Clear description of changes\n   - Test results\n   - Any related issue numbers\n\n### Code Review Criteria\n\n- ✓ Functionality works as intended\n- ✓ No security vulnerabilities introduced\n- ✓ Code style matches project standards\n- ✓ Adequate test coverage\n- ✓ Documentation updated\n- ✓ No regression of existing features\n\n## License\n\nThis project is licensed under the GNU General Public License v3.0 - see the [LICENSE](LICENSE) file for details.\n\n## Support\n\nFor bug reports, feature requests, or questions:\n- **Issues**: [GitHub Issues](https://github.com/Open-Technology-Foundation/clip/issues)\n- **Discussions**: Use issue tracker for general questions\n\n## Acknowledgments\n\nBuilt upon the foundation of:\n- **xclip** - X11 clipboard interface\n- **pngquant** - High-quality PNG compression\n- **optipng** - PNG optimizer\n- **ImageMagick** - Image processing toolkit\n\nDeveloped following the [Bash Coding Standard](https://github.com/Open-Technology-Foundation/bash-coding-standard) for professional-grade shell scripting.\n\n---\n\n**clip 1.0.1** - Professional clipboard utility for Linux | BCS Compliant | Zero Vulnerabilities\n\n#fin\n","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fopen-technology-foundation%2Fclip","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Fopen-technology-foundation%2Fclip","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fopen-technology-foundation%2Fclip/lists"}