Proposal: Show Different Single Character for Different Index States

[welcome-linja]

General information

System report (output of prompt_pure_system_report):

• Zsh: zsh 5.9 (x86_64-apple-darwin23.0) (/bin/zsh)
• Operating system: macOS 14.5 (23F79)
• Terminal program: Apple_Terminal (453)
• Tmux: no
• Git: git version 2.39.3 (Apple Git-146)
• Pure state:
  • username: ''
  • prompt: ❯
  • version: 1.23.0
• zsh-async version: 1.8.6
• PROMPT: typeset -g PROMPT=$'%F{${prompt_pure_colors[path]}}%~%f %{ %}%(12V.%F{$prompt_pure_colors[virtualenv]}%12v%f .)%(?.%F{$prompt_pure_colors[prompt:success]}.%F{$prompt_pure_colors[prompt:error]})${prompt_pure_state[prompt]}%f '
• Colors: typeset -g -A prompt_pure_colors=( [execution_time]=yellow [git:action]=yellow [git:arrow]=cyan [git:branch]=242 [git:branch:cached]=red [git:dirty]=218 [git:stash]=cyan [host]=242 [path]=blue [prompt:continuation]=242 [prompt:error]=red [prompt:success]=magenta [suspended_jobs]=red [user]=242 [user:root]=default [virtualenv]=242 )
• TERM: export TERM=xterm-256color
• Virtualenv: export VIRTUAL_ENV_DISABLE_PROMPT=12
• Conda: export CONDA_CHANGEPS1=no
• Detected frameworks: None

Rationale

I understand and support the reluctance to clutter the prompt, but as things currently stand, "local changes fully staged" and "unresolved merge conflicts" look exactly the same at a glance. Personally, I think that makes the status indicator not much more use than nothing at all.

Within the Pure philosophy, it isn't possible or desirable to display every detail of the repo state, but I believe we can show more than we currently are, without sacrificing aesthetic simplicity.

Proposal

I propose that instead of the * character Pure currently displays in all cases where the working tree differs from the current ref, it will instead display one of a selection of characters, depending on the first of these conditions to be satisfied:

• + if there are any untracked files
• * if there are any unstaged changes
• ^ if there are any staged changes

And of course defaulting to no character at all.

This way, the user always knows the most pertinent issue to resolve in the current tree, and not a single extra character is used over status quo.

Musings

• The listed characters are chosen to have roughly the same footprint but ascending elevation, as well as for a nerd reason; naturally any characters could be chosen, but I recommend a) keeping * to mean unstaged changes for continuity, and b) not directly copying p10k's defaults, as we already use * differently from them, and half-conformance is much worse than no conformance at all.
• There could be arguments made to have each character be a different colour, or not. I have no strong opinion on the matter.
• This idea opens up the possibility of also showing the presence of merge conflicts. I did not include these above because that would be a separate proposal, and also because I wasn't certain of the most natural place for them: in the tree state indicator, or as an additional/alternative decorator in the arrow area? I can see compelling arguments either way.

Further Reading

Issue #364 proposes a similar idea, but using multiple characters at once instead of one as described here.