merge-upstream

Files (1)

• SKILL.md

SKILL.md (first lines)

# Merge Upstream

Shannon tracks nushell and reedline as git subtrees under `nushell/` and
`reedline/`. Every few nushell releases, we pull upstream to pick up new
features and fixes. This skill captures what actually works — because
`scripts/sync-upstream.sh` alone is not enough when upstream has drifted.

## Why the script alone doesn't work

`scripts/sync-upstream.sh` runs `git subtree pull` for nushell and reedline,
then `cargo build && cargo test`. That's fine for tiny drifts. For real upstream
releases it fails because:

1. **Subtree auto-merge is noisy.** A hundred or more files will conflict — most
   of them files Shannon never touched. The auto-merger gets confused by rename
   chains and workspace-wide edits.
2. **Auto-merged files end up half-upstream, half-fork.** Even files that don't
   show conflicts can end up with stale content that references removed APIs.
   You won't see this until `cargo build` fails deep in `nu-protocol` or
   `nu-parser`.
3. **New upstream files get missed.** When auto-merge fights with the subtree
   prefix, new files upstream added may not appear in our tree at all — the
   build will complain about missing modules.
4. **Shannon's own `src/` lags upstream API.** `src/main.rs` and `src/run.rs`
   are copied from nushell's binary and drift every release.
5. **Root `Cargo.toml` version pins don't auto-bump.** The Shannon crate still
   references the old `0.N.0` nu-\* versions.
6. **Reedline must move in lockstep.** Nushell's workspace pins a specific
   reedline version; if you only pull nushell, the build fails because our
   vendored reedline is stale.

## Shannon's fork surface (the only 10 files we preserve)

Keep these exact files across upgrades. Everything else in `nushell/` should
come from upstream verbatim:

- `nushell/Cargo.toml` — workspace reedline path dep, shannon package renames
  (`shannon-nu-cli`, `shannon-nu-lsp`), shannon crate versions
- `nushell/crates/nu-cli/Cargo.toml` — `name = "shannon-nu-cli"`, tree-sitter
  deps for `BashHighlighter`
- `nushell/crates/nu-cli/src/bash_highlight.rs` — NEW, tree-sitter-based bash
  syntax highlighter
- `nushell/crates/nu-cli/src/mode_dispatcher.rs` — NEW, `ModeDispatcher` trait
- `nushell/crates/nu-cli/src/lib.rs` — declares `mod bash_highlight`,
  `mod mode_dispatcher`, and re-exports `BashHighlighter`, `ModeDispatcher`,
  `ModeResult`
- `nushell/crates/nu-cli/src/repl.rs` — dispatch hook in `loop_iteration()` that
  forwards to `ModeDispatcher::execute()` when `$env.SHANNON_MODE` is not
  `"nu"`; also a few smaller tweaks
- `nushell/crates/nu-cli/src/nu_highlight.rs` — small tweak
- `nushell/crates/nu-command/src/platform/input/input_.rs` — small tweak
- `nushell/crates/nu-lsp/Cargo.toml` — `name = "shannon-nu-lsp"`, references
  `shannon-nu-cli`

Verify this list against the current state before you start:

```sh
git diff --stat <last-nushell-import-commit>..HEAD -- nushell/
```

If new Shannon-modified files appear, add them to the preserve list below.

## The reliable procedure

Work on a branch — never on main.

### 1. Preflight

Clean working tree. Fetch upstream. Count the drift.

```sh
git status                                       # must be clean
git fetch upstream-nushell upstream-reedline
git log --oneline <last-merge-base>..upstream-nushell/main | wc -l
```

Large drifts (100+ commits) are the norm — that's fine, just plan for conflicts.

### 2. Branch off

```sh
git checkout -b upgrade/nushell-$(date +%Y-%m-%d)
```

### 3. Pull nushell (expect conflicts)

```sh
git subtree pull --prefix nushell upstream-nushell main \
  -m "Merge nushell upstream $(date +%Y-%m-%d)"
```

This will fail with "Automatic merge failed". That is expected.

### 4. Save Shannon's fork files to /tmp

Before doing anything destructive:

```sh
mkdir -p /tmp/shannon_patches
cp nushell/Cargo.toml                                       /tmp/shannon_patches/Cargo.toml
cp nushell/crates/nu-cli/Cargo.toml                         /tmp/shannon_patches/nu-cli-Cargo.toml
cp nushell/crates/nu-cli/src/bash_highlight.rs              /tmp/shannon_patches/bash_highlight.rs
cp nushell/crates/nu-cli/src/mode_dispatcher.rs             /tmp/shannon_patches/mode_dispatcher.rs
cp nushell/crates/nu-cli/src/lib.rs                         /tmp/shannon_patches/lib.rs
cp nushell/crates/nu-cli/src/nu_highlight.rs                /tmp/shannon_patches/nu_highlight.rs
cp nushell/crates/nu-cli/src/repl.rs                        /tmp/shannon_patches/repl.rs
cp nushell/crates/nu-command/src/platform/input/input_.rs   /tmp/shannon_patches/input_.rs
cp nushell/crates/nu-lsp/Cargo.toml                         /tmp/shannon_patches/nu-lsp-Cargo.toml
```

The unresolved conflict markers in those files are fine — they're snapshots, not
for reuse. What you actually need from them is the Shannon side of each hunk,
which you'll recreate by hand in step 7. In practice the easier workflow is:
commit the broken merge first (step 5), then re-export clean Shannon versions
from the main branch:

```sh
git show main:nushell/Cargo.toml > /tmp/shannon_patches/Cargo.toml
# ... and so on

From shannonshell/shannon, MIT.

More from shannonshell/shannon