Emphasize that "status {list-files,get-file}" are meant for internal use

I'm not aware of a lot of sensible use cases where users need to access
our files directly.  The one example we know about is zoxide overriding
exactly our version of "function cd", ignoring any user-provided cd.
I think this is already hacky. But I guess it's here to stay.

I think we should not recommend this for external use, or at least
ask users to tell us what they are using this for.

Given that we expect these to be used mainly/only internally,
get-file/list-files are fine as names.

The other issue is that one has to be careful to always do

	status list-files 2>/dev/null

to support non-embedded builds.

Closes #11555
This commit is contained in:
Johannes Altmanninger
2025-09-27 13:04:12 +02:00
parent b964072c11
commit aba4d26f95
2 changed files with 9 additions and 2 deletions

View File

@@ -110,12 +110,18 @@ The following operations (subcommands) are available:
This prints information on how fish was build - which architecture, which build system or profile was used, etc.
This is mainly useful for debugging.
.. _status-get-file:
**get-file** *FILE*
NOTE: this subcommand is mainly intended for fish's internal use; let us know if you want to use it elsewhere.
This prints a file embedded in the fish binary at compile time. This includes the default set of functions and completions,
as well as the man pages and themes. Which files are included depends on build settings.
Returns 0 if the file was included, 1 otherwise.
**list-files** *FILE*
NOTE: this subcommand is mainly intended for fish's internal use; let us know if you want to use it elsewhere.
This lists the files embedded in the fish binary at compile time. Only files where the path starts with the optional *FILE* argument are shown.
Returns 0 if something was printed, 1 otherwise.