This looks good! I think it's worth keeping the old names around, though - I can see a few uses of them in third-party repositories and so on.

I am not sure about "un-dundering", and I'd appreciate other thoughts. There are lots of these completion-helper type functions (__fish_commandline_is_singlequoted, __fish_contains_opt, __fish_not_contain_opt - in fact about fourteen or so! Should we promote them all to documented, guaranteed functions? Or just start with this one?

I think it's OK to have some duplication here, and only promote them as needed.

I think it's worth keeping the old names around, though - I can see a few uses of them in third-party repositories and so on.

Do you mean that I should keep both share/function/__fish_is_token_n.fish and share/function/__fish_is_nth_token.fish around?

I was also thinking of editing the description for fish_is_nth_token to "Test if current token is the n-th non-switch argument".

I am not sure about "un-dundering", and I'd appreciate other thoughts.

So, as it is currently, we use the dunder to signal one or both of two things:

1. It's an internal thing that doesn't have a compatibility "guarantee". We can change it at will
2. It's not something you should see when tab-completing commands because it's not useful at the commandline itself. (tab completions ignore commands starting with an underscore)

The first would only really be of use if we ever decided to "stabilize" something by un-dundering it. And since we currently don't do so, in practice dundered functions are used all over the place and we don't really have the moral authority to tell people to stop using them, and so we don't want to break them. We even recommend dundered methods in the docs! (in practice we do limited compatibility breaks anyway and it works out alright)

The second is generally used for completion helpers like these that don't appear in "ordinary" fish script. You wouldn't use this in your prompt.

So to achieve having a layer of "unstable" or "internal" functions, we would have to un-dunder some, but that loses the property of having them ignored in completions. I'm not super sure if that's useful, and we could also use a single underscore instead and document that convention (we've attempted that before with _fish_systemctl).

Or we could decide that we don't really break compatibility in these a lot and we don't need the first property, in which case it's down to the aesthetics of the dunderscore vs having these show up in completions.

I'm also not really sold that any convention will actually be followed by our users - look at how some people still hit the ^ redirection even tho we've signalled that fairly loudly and added the means to try it out.

And once we un-dunder one thing (that's not user-facing like fish_git_prompt - which we have undundered), we should probably commit to doing that more, or we end up more inconsistent than before. Is that worth it? Can we say which functions are really "stable"? What convention should we use?

TL;DR: Dunno?

In the interest of moving this along (sorry, @anrddh):

As far as I can see, there's a few different kinds of dundered functions:

• Compatibility guff nobody should use, including stuff to paper over platform differences (__fish_md5) and stuff kept for compatibility (__fish_abbr_old), especially after undundering (__fish_git_prompt)
• Internal things (__fish_config_interactive, __fish_describe_command)
• Key binding helpers (__fish_list_current_token)
• Completion helpers that are only useful to a specific set of completions (__fish_complete_clang is shared across clang and clang++, generally everything beginning with __fish_print or __fish_complete)
• Helper functions that are generally useful (__fish_contains_opt, __fish_seen_subcommand_from, this)

Of these, I would propose that we undunder and stabilize the key binding helpers and the generally useful helpers.

All other things are, in some sense, "internal". __fish_complete_clang is "internal" to clang and clang++. It's only a function file so those completions have a place to share it, and because having a different directory for them to explicitly source it is annoying.

So that means this can go in, other functions can start being undundered, documented, stabilized and cleaned up. We should start to figure out a deprecation system that works for these as well (#8131).

Unless anyone objects, I would like to merge this PR this weekend, and we can eventually start moving on the rest (although it's not critical, there's no rush).

2. It's not something you should see when tab-completing commands because it's not useful at the commandline itself.

I hadn't thought of this, but it's a useful consideration. But fishTab already produces a lot of not-terribly-useful functions, so I think your plan above is good.

I've cleaned up the branch and commits. Please let me know if you'd like me to make any other changes.

Merged, thanks!