fish_vcs_prompt: improve format string idea and document it

[ammgws]

As mentioned in #7033 and on Reddit, fish_git_prompt can be supplied a string to format its output.

This is little known, but fish_git_prompt (that's the name in fish 3.1, the old one with the dunders is kept for compatibility) takes a "format string" (this was at one point supposed to do more but didn't really pan out). It defaults to (%s), so if you want to leave off the parens just call fish_git_prompt %s.

This feature is undocumented, however it is quite rudimentary and IIRC not available in the svn or hg prompts, so before documenting it someone may want to work on those points.

[faho]

Yeah, I have a working prototype. My question is what this should include? What is this useful for? One possibility is to replace the terlar git prompt with just a standard set of arguments to the main prompt. Also we might want to skip computing things we won't display.

As I currently have it, you'd give a list of words for what you want to have where, like

fish_git_prompt branch dirty upstream

and that would then print the branch, the dirty-state and the upstream-state. Any unrecognized word is currently printed as-is, tho I think we want to ignore anything that looks like a word to make it more cross-compatible across versions.

The code for this is actually acceptable, it's just a little weird that it accepts the arguments as a list yet won't print a space between them.

Also I'm not sold on the need to reorder these things, and I have not found a nice way to specify e.g. "only print a separator here if there is something".

It looks like this:

[shlemas]

Just to throw an idea out, what if fish provided something like:

function fish_git_prompt_custom -a custom_func
    # Gather all the git repo data, etc.
    ...
    $custom_func $branch $upstream $dirty
end

And then users could do something like:

function git_formatter -a branch upstream dirty
    # I can arbitrarily format my own string with the data passed in by fish_git_prompt_custom.
    echo "[$branch] ($upstream | $dirty)"
end

function fish_prompt
    printf "%s %s" (pwd) (fish_git_prompt_custom git_formatter)
end

Edit: On second thought, I don't like my suggestion because the positional arguments would be inflexible and could basically never change. I believe I remember seeing discussion in another issue where someone suggested calling a function that would set some variables that you could then reference freely within your own function, and that's probably the better approach that still gets you the same sort of end result. Can't find the issue now though.

[ariasuni]

I’m not sure if this is relevant but I find it annoying to not be able to reorder dirtystate/stagedstate/stashstate/untrackedfile/invalidstate. Maybe we should be able to use something like this?

fish-shell/share/functions/fish_git_prompt.fish

Line 513 in f75cf5c

set -g ___fish_git_prompt_status_order stagedstate invalidstate dirtystate untrackedfiles stashstate

I’m not sure where you want to draw the line between what should be available in fish out-of-the-box, and what should be be let to more advanced (sometimes cross-shell) prompts like silver or starship.

[faho]

Maybe we should be able to use something like this?

So presumably all that needs to be done is to only use that value as the default?

[ariasuni]

I’m not really sure. Now that the order has been changed (in 7116627), I don’t need this feature.

I guess it would be useful to know who:

• Uses fish_git_prompt, and would like these configuration options
• Uses another solution, but would prefer using fish_git_prompt if it had these configuration options

Because advanced users may also want to reorder branch/statuses/special states (ongoing merge, rebase, etc.), but you if you offer to configure this, a format string makes it hard to handles spaces properly when one item is not displayed because irrelevant, etc.

[faho]

Oh, what I meant was to allow that variable to work we just need to do

set -q __fish_git_prompt_status_order
or set -g __fish_git_prompt_status_order ....

This used to set the variable unconditionally when fish_git_prompt was loaded, so if you set that in config.fish it would be overwritten.

But I've then noticed that we weren't actually using it in the non-informative mode.

[wesruv]

I'm not entirely sure I understand this ticket, but I think this might be helpful feedback?

I've been looking for how to remove the ( prefix and ) suffix in fish_git_prompt for some time now, and I'm very thankful for the top comment in this issue. Using %s after fish_git_prompt does exactly what I wanted.

The why of printf (fish_git_prompt %s) or what %s means is completely opaque to me. Now that I have the answer, and I looked back at the docs, I'm not sure where I would have figured it out, or how to figure out what %s is about.

For context, I'm an:

• intermediate CLI user
• a copy paste monkey when it comes to fish config
• was able to figure out how to write some custom fish functions
• professional web developer by day (professional HTML/CSS/JS coder)