# Plugin Exclusion Guide\n\n## Quick Reference\n\n**What is plugin exclusion?**: A mechanism to prevent certain plugins (like `nu_plugin_example`) from being included in distributions and installations, while keeping them available for development and testing.\n\n**Who should read this?**:\n\n- 📦 Release managers\n- 👨💻 Plugin developers\n- 🔧 Maintainers\n- 📚 Users who want to understand the distribution process\n\n---\n\n## Quick Start\n\n### For Users\n\n**Question**: I found `nu_plugin_example` but it's not in my installation. Why?\n\n**Answer**: The example plugin is intentionally excluded from distributions. It's a reference implementation for plugin developers, not a user-facing tool.\n\n**If you want to use it**:\n\n1. Clone the repository\n2. Build it: `just build`\n3. Use the binary directly: `./nushell/target/release/nu_plugin_example`\n\n---\n\n### For Developers\n\n**Question**: I want to exclude my plugin from distributions. How?\n\n**Answer**: Add it to the exclusion list in `etc/plugin_registry.toml`:\n\n```toml\n[distribution]\nexcluded_plugins = [\n "nu_plugin_example",\n "nu_plugin_my_new_plugin" # ← Add your plugin here\n]\n```\n\nThat's it! The collection and packaging systems will automatically skip it.\n\n---\n\n### For Release Managers\n\n**Checklist before release**:\n\n1. **Verify exclusion list is correct**:\n\n ```bash\n nu -c "open ./etc/plugin_registry.toml | get distribution.excluded_plugins"\n ```\n\n2. **Verify collection respects it**:\n\n ```bash\n just collect\n find distribution -name "*example*" # Should find nothing\n ```\n\n3. **Verify packaging respects it**:\n\n ```bash\n just pack-full\n tar -tzf bin_archives/*.tar.gz | grep example # Should find nothing\n ```\n\n4. **Verify builds still include everything** (for testing):\n\n ```bash\n just build\n ls nushell/target/release/ | grep example # Should find the binary\n ```\n\n---\n\n## Common Tasks\n\n### Task 1: Add a Plugin to Exclusion List\n\n**Scenario**: You have a new reference plugin that shouldn't be shipped to users.\n\n**Steps**:\n\n1. Create your plugin in `nushell/crates/nu_plugin_myref/`\n2. Update `etc/plugin_registry.toml`:\n\n ```toml\n [distribution]\n excluded_plugins = [\n "nu_plugin_example",\n "nu_plugin_myref" # ← Add here\n ]\n ```\n\n3. Update `scripts/templates/default_config.nu` - remove it from the `plugin_binaries` list if it was there\n4. Test:\n\n ```bash\n just collect && find distribution -name "*myref*" # Should be empty\n ```\n\n---\n\n### Task 2: Remove a Plugin from Exclusion List\n\n**Scenario**: Your reference plugin is now stable and ready for distribution.\n\n**Steps**:\n\n1. Update `etc/plugin_registry.toml`:\n\n ```toml\n [distribution]\n excluded_plugins = [\n "nu_plugin_example" # ← Removed your plugin\n ]\n ```\n\n2. Update `scripts/templates/default_config.nu` - add it to the `plugin_binaries` list if you want auto-loading\n3. Test:\n\n ```bash\n just collect && find distribution -name "*myref*" # Should exist now\n ```\n\n---\n\n### Task 3: Check Current Build Includes Excluded Plugin\n\n**Scenario**: You want to verify that excluded plugins are still being built.\n\n**Steps**:\n\n```bash\n# Build everything including excluded plugins\njust build\n\n# Verify excluded plugin was built\nls nushell/target/release/nu_plugin_example\n# Output: nushell/target/release/nu_plugin_example\n```\n\n**Why?** Excluded plugins are still useful for:\n\n- Testing and validation\n- Reference implementations\n- Developer documentation\n- Internal reference\n\n---\n\n### Task 4: Understand Distribution Workflow\n\n**Scenario**: You want to understand how plugins flow through the build/collect/package process.\n\n**Diagram**:\n\n```plaintext\nSOURCE (all plugins built)\n├── nu_plugin_example (excluded)\n├── nu_plugin_auth\n├── nu_plugin_kms\n└── ... others\n\n ↓ (just build - NO filtering)\n\nBUILD OUTPUT (target/release)\n├── nu_plugin_example ✅ (built)\
