nushell-plugins/docs/PLUGIN_EXCLUSION_GUIDE.md

Plugin Exclusion Guide

Quick Reference

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.

Who should read this?:

• 📦 Release managers
• 👨‍💻 Plugin developers
• 🔧 Maintainers
• 📚 Users who want to understand the distribution process

---

Quick Start

For Users

Question: I found nu_plugin_example but it's not in my installation. Why?

Answer: The example plugin is intentionally excluded from distributions. It's a reference implementation for plugin developers, not a user-facing tool.

If you want to use it:

1. Clone the repository
2. Build it: just build
3. Use the binary directly: ./nushell/target/release/nu_plugin_example

---

For Developers

Question: I want to exclude my plugin from distributions. How?

Answer: Add it to the exclusion list in etc/plugin_registry.toml:

[distribution]
excluded_plugins = [
    "nu_plugin_example",
    "nu_plugin_my_new_plugin"  # ← Add your plugin here
]

That's it! The collection and packaging systems will automatically skip it.

---

For Release Managers

Checklist before release:

1. Verify exclusion list is correct:

   nu -c "open ./etc/plugin_registry.toml | get distribution.excluded_plugins"
   

2. Verify collection respects it:

   just collect
   find distribution -name "*example*"  # Should find nothing
   

3. Verify packaging respects it:

   just pack-full
   tar -tzf bin_archives/*.tar.gz | grep example  # Should find nothing
   

4. Verify builds still include everything (for testing):

   just build
   ls nushell/target/release/ | grep example  # Should find the binary
   

---

Common Tasks

Task 1: Add a Plugin to Exclusion List

Scenario: You have a new reference plugin that shouldn't be shipped to users.

Steps:

1. Create your plugin in nushell/crates/nu_plugin_myref/
2. Update etc/plugin_registry.toml:

   [distribution]
   excluded_plugins = [
       "nu_plugin_example",
       "nu_plugin_myref"  # ← Add here
   ]
   

3. Update scripts/templates/default_config.nu - remove it from the plugin_binaries list if it was there
4. Test:

   just collect && find distribution -name "*myref*"  # Should be empty
   

---

Task 2: Remove a Plugin from Exclusion List

Scenario: Your reference plugin is now stable and ready for distribution.

Steps:

1. Update etc/plugin_registry.toml:

   [distribution]
   excluded_plugins = [
       "nu_plugin_example"  # ← Removed your plugin
   ]
   

2. Update scripts/templates/default_config.nu - add it to the plugin_binaries list if you want auto-loading
3. Test:

   just collect && find distribution -name "*myref*"  # Should exist now
   

---

Task 3: Check Current Build Includes Excluded Plugin

Scenario: You want to verify that excluded plugins are still being built.

Steps:

# Build everything including excluded plugins
just build

# Verify excluded plugin was built
ls nushell/target/release/nu_plugin_example
# Output: nushell/target/release/nu_plugin_example

Why? Excluded plugins are still useful for:

• Testing and validation
• Reference implementations
• Developer documentation
• Internal reference

---

Task 4: Understand Distribution Workflow

Scenario: You want to understand how plugins flow through the build/collect/package process.

Diagram:

SOURCE (all plugins built)
├── nu_plugin_example (excluded)
├── nu_plugin_auth
├── nu_plugin_kms
└── ... others

  ↓ (just build - NO filtering)

BUILD OUTPUT (target/release)
├── nu_plugin_example ✅ (built)
├── nu_plugin_auth ✅ (built)
├── nu_plugin_kms ✅ (built)
└── ... others ✅ (built)

  ↓ (just collect - WITH filtering)

COLLECTION (distribution/)
├── nu_plugin_example ❌ (excluded)
├── nu_plugin_auth ✅ (collected)
├── nu_plugin_kms ✅ (collected)
└── ... others ✅ (collected)

  ↓ (just pack - WITH filtering)

PACKAGING (bin_archives/)
├── nushell-0.109.0-linux-x64.tar.gz
│   ├── nu
│   ├── nu_plugin_auth ✅
│   ├── nu_plugin_kms ✅
│   └── ... (no example plugin)
└── nushell-0.109.0-darwin-arm64.tar.gz
    ├── nu
    ├── nu_plugin_auth ✅
    ├── nu_plugin_kms ✅
    └── ... (no example plugin)

  ↓ (installation)

USER SYSTEM
├── ~/.local/bin/nu ✅
├── ~/.local/bin/nu_plugin_auth ✅
├── ~/.local/bin/nu_plugin_kms ✅
├── ~/.config/nushell/env.nu
└── ~/.config/nushell/config.nu (auto-loads auth, kms; example not in list)

---

Technical Details

How Exclusion Works

Mechanism: The system reads etc/plugin_registry.toml and filters at two points:

1. Collection (just collect / just collect-full):

   • Reads exclusion list from registry
   • Skips excluded plugins during binary collection
   • Result: distribution/ dir doesn't have excluded plugins

2. Packaging (just pack / just pack-full):

   • Reads exclusion list from registry
   • Skips excluded plugins during package creation
   • Result: bin_archives/*.tar.gz don't have excluded plugins

3. Installation (auto-load configuration):

   • scripts/templates/default_config.nu manually removes excluded plugins from the auto-load list
   • Result: User installations don't auto-load excluded plugins

Files Involved

File	Role
etc/plugin_registry.toml	Source of truth for exclusion list
scripts/collect_full_binaries.nu	Implements collection-time filtering
scripts/create_distribution_packages.nu	Implements packaging-time filtering
scripts/templates/default_config.nu	Defines auto-load list (manually edited)
justfile + justfiles/*.just	Provides build/collect/pack commands

Registry Format

[distribution]
excluded_plugins = [
    "nu_plugin_example"        # Plugin directory name
]
reason = "Reference plugin"    # Documentation (optional)

Key Points:

• excluded_plugins is a list of plugin directory names (not binary names)
• Must match the nu_plugin_* directory in the repo
• Case-sensitive
• Empty list [] means no exclusions

---

Troubleshooting

Problem: Excluded Plugin Still Appears in Distribution

Possible Causes:

1. Registry file not saved properly
2. Collection script using cached data
3. Plugin name mismatch

Solution:

# Verify registry is correct
nu -c "open ./etc/plugin_registry.toml | get distribution.excluded_plugins"

# Clean and rebuild
rm -rf distribution bin_archives
just collect
find distribution -name "*example*"  # Should be empty

---

Problem: Can't Find Excluded Plugin After Build

Expected Behavior: Excluded plugins ARE still built (just not distributed)

Verification:

just build
ls nushell/target/release/nu_plugin_example  # Should exist

# If it doesn't, the plugin may not be in the build system
just build-nushell --verbose

---

Problem: Manual Plugin Registration Failing

Issue: User manually adds excluded plugin but it doesn't work

Cause: Plugin binary not in PATH

Solution:

# Build the plugin
just build

# Use full path
./nushell/target/release/nu_plugin_example --version

# Or install it manually
cp ./nushell/target/release/nu_plugin_example ~/.local/bin/
nu -c "plugin add ~/.local/bin/nu_plugin_example"

---

FAQs

Q: Will my excluded plugin still be tested? A: Yes. Excluded plugins are still built and tested. They're only excluded from user-facing distributions.

Q: Can I exclude a plugin from builds but not distributions? A: No, the current system doesn't support this. The exclusion system only affects distribution. To exclude from builds, use Cargo features.

Q: Can different distributions have different exclusion lists? A: Not currently, but this is planned as a future enhancement (profile-based exclusions).

Q: What happens if I exclude a plugin that doesn't exist? A: It's ignored. The filtering works by checking if a plugin name is in the exclusion list, so non-existent plugins are silently skipped.

Q: Can I exclude plugins selectively (e.g., exclude from macOS but not Linux)? A: Not currently. This would require platform-based exclusion profiles (future enhancement).

---

Best Practices

✅ DO

• Update the comment in config when excluding/including plugins
• Test after changes: just collect && just pack-full && just build
• Document the reason in plugin_registry.toml (optional but recommended)
• Run verification before releases (see Release Manager checklist)
• Keep registry clean - don't exclude plugins you won't maintain

❌ DON'T

• Edit multiple files - only touch etc/plugin_registry.toml for the core change
• Assume exclusion happens at build time - it only happens during collect/pack
• Forget to test - exclusion changes should be verified before release
• Add plugins to exclusion list without documenting why in the code
• Exclude plugins that users depend on - use this only for reference/experimental plugins

---

Integration with CI/CD

GitHub Actions Example

name: Distribution Release

on:
  push:
    tags:
      - 'v*'

jobs:
  release:
    runs-on: ubuntu-latest
    steps:
      - uses: actions/checkout@v3

      # Verify exclusion list
      - name: Verify Exclusion List
        run: |
          nu -c "open ./etc/plugin_registry.toml | get distribution.excluded_plugins"

      # Build (includes all plugins)
      - name: Build
        run: just build-full-release

      # Collect (excludes specified plugins)
      - name: Collect
        run: just collect-full

      # Verify excluded plugins not in distribution
      - name: Verify Exclusions
        run: |
          ! find distribution -name "*example*"

      # Package
      - name: Package
        run: just pack-full-checksums

      # Release
      - name: Create Release
        uses: softprops/action-gh-release@v1
        with:
          files: bin_archives/*

---

See Also

• Architecture Details: docs/architecture/PLUGIN_EXCLUSION_SYSTEM.md
• Build System: docs/BUILDING.md
• Plugin Development: nushell/crates/nu_plugin_example/ (reference implementation)
• Registry Configuration: etc/plugin_registry.toml

---

Version: 1.0.0 Last Updated: 2025-12-03 Status: Stable