this is less discoverable than grep, so maybe not worth it

I think it's simpler and more discoverable in at least two cases:

1. I'm running a number of commands interactively that I'm trying to understand better, and I don't have to think about how or where to add grep on each one.
2. I'm writing a script. I want to debug by showing what commands are being run without adding a lot of echos, and I don't want to need exec tricks, extra scopes, or a wrapper script for grep.

In other words, fish_trace_depth is useful in more complex scenarios, which is exactly where you might want fish_trace in the first place.

In both cases, it's helpful to see a level or two of depth, but not the full trace that shows complete function expansions, etc., so it's convenient to have this one obvious setting.

Other tests:

• set the depth based on specific context (e.g. only deep traces for i=2, don't care about i=1 or i=3 so shallow traces)
• setting a deep depth after going beyond the current max, i.e. a discontinuity in the depth (e.g. start with a depth of 1, then when at the script is a depth 3, set the depth to 4)
• set the depth in a local scope (variant of the specific context above, but with automatic reset)

@Nahor I've pushed an update that hopefully addresses your requests. Let me know if I didn't understand and I can adjust.

I'm writing a script.

I think one alternative is fish_trace=1 fish -c 'echo 123' &| grep -E '^-{0,2}>'

I'm running a number of commands interactively that I'm trying to understand better, and I don't have to think about how or where to add grep on each one.

Hmm maybe interactive shell+terminal is not an ideal environment for this.
Wouldn't it be better to pipe the entire fish_trace into an editor window, and then tell the editor to collapse at a given level.

Not sure yet. Do you have a concrete example where you find this useful?
I've never really filtered the entire output like this but I think I sometimes filter jump between matches of ^--> in the editor or pager.

Do you have a concrete example where you find this useful?

Sure. I write a lot of scripts for myself - to manage my system, call other tools, etc. I'm switching to fish because it's a nicer language than bash and I believe in where it's headed. Because the scripts are for myself, I don't need fancy output, but I do want to know what's happening at various points. fish_trace is perfect for this, but it shows way more than is helpful for this case. I don't need to know the complete depth of expansion for every function; for example, the built-in cd function expands to 27 lines of trace, mostly at depths 2 and 3. Setting a trap prints 41 lines down to depth 7. If I can set depth to 0 or 1, I can see the commands I actually wrote, without so many implementation details.

I think one alternative is fish_trace=1 fish -c 'echo 123' &| grep -E '^-{0,2}>'

Sure, and I'm sure there are other clever ways to do it as well, but if I have to wrap scripts to get useful output, it doesn't seem very friendly, and I'm probably not going to do it.

Interesting. For simple scripts, I still use POSIX sh (where set -x; cd won't have noisy output) and for larger ones maybe Python.
Your explanation makes sense.
But this approach seems not quite perfect -- it will not work well if you use lots of if, while and other block statements.
Maybe what you really want is a feature to trace all commands in the current file?
Or if you use separate files for functions, all user-defined functions in ~/.config/fish/functions/ ?
Maybe something like fish_trace=user would make sense.

I agree that fish_trace=user would be nice. I mentioned a similar idea in the linked issue, fish_trace=exec, which would only show external commands that fish runs. I'm sure other filter types could be useful in different cases.

I think that what gets traced is orthogonal to how far it gets traced, and both are useful. I've done the first (admittedly easier) part in this PR, which would solve my current issue, and I'd love to see trace filters in the future as well.