nushell-plugins/guides

Nushell Plugins - Guides Directory

Comprehensive guides for nushell plugin development and version management

---

📚 Available Guides

🚀 Quick Start

QUICK_START.md - Fast track to updating Nushell and creating distributions

Perfect for: Getting started immediately, common workflows, quick reference

Key topics:

• One-liner updates
• Creating distributions and bin archives
• Common workflows
• Status commands
• Troubleshooting

---

📖 Complete Version Update Guide

COMPLETE_VERSION_UPDATE_GUIDE.md - Comprehensive guide for updating Nushell versions

Perfect for: Understanding the complete update process, step-by-step instructions

Key topics:

• Complete update workflow (all phases)
• Plugin updates
• Distribution creation
• Validation and testing
• Troubleshooting
• Reference commands

---

🗂️ Version-Specific Documentation

Version-specific documentation is located in the updates/ directory:

updates/
├── 107/              # Nushell 0.107.x documentation
├── 108/              # Nushell 0.108.x documentation
│   ├── NUSHELL_0.108_UPDATE_SUMMARY.md       # Complete update summary
│   ├── MIGRATION_0.108.0.md                  # Migration guide
│   ├── NUSHELL_UPDATE_AUTOMATION.md          # Automation documentation
│   └── ... (validation reports, change logs)
└── 109/              # Future versions...

---

🎯 Quick Navigation

I want to...

...update to a new Nushell version → Read: QUICK_START.md → Run: just complete-update 0.108.0

...create distribution packages → Read: QUICK_START.md → Run: just create-distribution

...update only plugins → Read: QUICK_START.md → Run: just update-plugins 0.108.0

...understand the complete process → Read: COMPLETE_VERSION_UPDATE_GUIDE.md

...check migration requirements → Read: updates/108/MIGRATION_0.108.0.md

...understand the automation → Read: updates/108/NUSHELL_UPDATE_AUTOMATION.md

---

🔧 Command Quick Reference

Update Commands

# Complete update
just complete-update 0.108.0          # All-in-one
just update-latest                     # Latest version

# Step-by-step
just update-nushell 0.108.0           # Nushell core only
just update-plugins 0.108.0           # Plugins only
just create-distribution              # Distributions only

Status Commands

just update-status                    # Update system status
just dist-status                      # Distribution status
just check-versions                   # Version consistency
just list-versions                    # List plugin versions
just audit-deps                       # Dependency audit

Help Commands

just update-help                      # Quick command reference
just update-docs                      # Documentation paths
just help                            # All available commands

---

📖 Documentation Structure

Repository Documentation:
├── guides/                           # This directory
│   ├── README.md                     # This file
│   ├── QUICK_START.md                # Fast track guide
│   └── COMPLETE_VERSION_UPDATE_GUIDE.md  # Complete guide
│
├── updates/                          # Version-specific docs
│   ├── 107/
│   ├── 108/
│   │   ├── NUSHELL_0.108_UPDATE_SUMMARY.md
│   │   ├── MIGRATION_0.108.0.md
│   │   ├── NUSHELL_UPDATE_AUTOMATION.md
│   │   └── ... (validation, changes, etc.)
│   └── 109/
│
├── README.md                         # Repository overview
├── CHANGELOG.md                      # All changes
├── CLAUDE.md                         # Claude Code guidance
│
└── scripts/                          # Automation scripts
    ├── complete_update.nu            # All-in-one updater
    ├── update_all_plugins.nu         # Bulk plugin updater
    ├── create_full_distribution.nu   # Distribution creator
    └── ... (8 total update scripts)

---

🎓 Learning Path

For First-Time Users

1. Start here: QUICK_START.md

   • Learn the one-liner update command
   • Understand what gets created

2. Then read: Repository README.md

   • Understand repository structure
   • Learn about plugin types

3. For deeper knowledge: COMPLETE_VERSION_UPDATE_GUIDE.md

   • Complete workflow understanding
   • Troubleshooting guide

For Experienced Users

1. Quick Reference: QUICK_START.md

   • Command cheat sheet
   • Common workflows

2. Automation Details: updates/108/NUSHELL_UPDATE_AUTOMATION.md

   • How automation works
   • Customization options

3. Version Changes: updates/108/MIGRATION_0.108.0.md

   • Breaking changes
   • Migration steps

---

💡 Tips & Best Practices

Before Updating

✅ Always check for breaking changes:

just detect-breaking

✅ Create a backup:

git stash save "backup before update"

✅ Check current versions:

just check-versions
just audit-deps

During Update

✅ Use the all-in-one command for simplicity:

just complete-update 0.108.0

✅ Monitor progress:

just update-status

After Update

✅ Validate everything works:

just validate-code
just verify-plugins

✅ Create distributions:

just create-distribution-all

✅ Commit changes:

git add -A
git commit -m "chore: update to Nushell 0.108.0"

---

🆘 Getting Help

Quick Help

# Show all update commands
just update-help

# Show documentation paths
just update-docs

# Show all available commands
just help

Documentation

• This file: Overview and navigation
• QUICK_START.md: Fast track and common workflows
• COMPLETE_VERSION_UPDATE_GUIDE.md: Comprehensive guide
• updates/108/: Version-specific documentation

Online Resources

• Nushell Book
• Plugin Development
• GitHub Releases

---

🔄 Update Workflow Summary

graph TD
    A[Start: New Nushell Version] --> B{Choose Workflow}
    B -->|All-in-One| C[just complete-update 0.108.0]
    B -->|Step-by-Step| D[just update-nushell 0.108.0]

    C --> Z[Done! ✅]

    D --> E[just update-plugins 0.108.0]
    E --> F[just create-distribution]
    F --> G[just validate-code]
    G --> Z

    Z --> H[Commit Changes]
    H --> I[Push to Repository]

---

Last Updated: 2025-10-18 Current Nushell Version: 0.108.0 Guides Status: ✅ Complete and ready to use