Spaceship-prompt: proposal: fuller support for user-defined sections

[olets]

Opening this issue inspired by the conversation at https://github.com/denysdovhan/spaceship-prompt/issues/479#issuecomment-409102093

Related to discussion #375, and PRs #362, #391, #392, #393

I've come to think that supplying several significantly different flavors for individual sections isn't the way to go.

Currently when considering new section PRs, maintainers just have to ask the fairly objective question of whether it fits with Spaceship. With this door opened, there could be a lot of PRs for niche sections, and maintainers would have to make very subjective calls about what's good enough. I'm not sure that's a good idea: it doesn't sound fun for the maintainers, and it could add unhappiness to the community. And in the end there will be people whose custom sections didn't make the cut who want a good way to make their custom sections available.

When we first started talking about the Git section, Denys's initial reaction was they should just be custom sections. I think that's the way to go, but it needs to graduate from "add to the wiki, and check the wiki for sections you want to add to your local copy":

1. there should be a user-friendly way to add custom sections, _without touching Spaceship_
2. Spaceship should look for user sections
3. maybe there should be an officially-recognized, installable, lightly curated collection of third-party sections (maybe this repo, maybe a different repo)

Re 1 and 2: Adding a SPACESHIP_CUSTOM_SECTIONS_DIR and looking there for section definitions is straight forward.

Re 3: maybe just have users manually download sections and add them to the user sections' directory. If the sourcing and spaceship::defined searched that directory recursively, a user could have my-spaceship-sections/personal/... and my-spaceship-sections/downloaded/...

If I remember correctly (it's been a couple months since I had time to look at this) there's something goofy with spaceship::defined giving false negatives to the custom sections I've added locally. If that's the case, fixing it is probably the only complicated prerequisite for this enhancement

Then there's just #407 (tldr; maybe just a question of updating the documentation, but maybe refactoring some of Spaceship's lower level workings). Only the sections included in SPACESHIP_PROMPT_ORDER should be sourced

I'd be happy to PR something like this!

I don't have time to work on it immediately. What's the 4.0 timeline?

[maximbaz]

I think the main complexity comes not from loading custom sections, but with placing them in the specific position in $SPACESHIP_PROMPT_ORDER. For example, let's assume I came up with an alternative jobs section and want to replace the original jobs with my-jobs. How do I do that without completely overriding $SPACESHIP_PROMPT_ORDER? Because I still want to automatically get new sections as spaceship evolves.

391 was an attempt to solve it, but as mentioned earlier I personally don't think that's the right approach, it maybe solves one specific problem (git) but adds complexity and doesn't cover all other cases (e.g. replacing jobs with my-jobs).

[olets]

solves one specific problem (git) but adds complexity and doesn't cover all other cases

Exactly. When I first started working on that I thought it was reasonable because the Git section stood out as being one of the few that was more than just a simple value. But now I've written additional sections for myself, and I bet you have too, and looking at #479 I bet there's room to customize many of the sections in ways I haven't thought of.

What I'm seeing is a desire for and value in a solid prompt tool that offers complete customization. Spaceship is in the perfect position to be that tool.

How do I do[replace the original jobs with my-jobs] without completely overriding $SPACESHIP_PROMPT_ORDER

Cool, I can see wanting to do that. Probably support this lower down. e.g. in the override's file name and/or function name. Not sure how the sourcing would work but I'm sure it could be done

I still want to automatically get new sections as spaceship evolves.

Great point. Hadn't thought about it, yes that would be nice. But that's a separate issue: users who customize their prompt order should still (optionally) see any new sections Spaceship adds. I'll play with that this weekend if you don't beat me to it.

[maximbaz]

I've been scratching my head for a while on this, honestly I see no good way how to achieve both points, customize $SPACESHIP_PROMPT_ORDER and keep getting new sections. Even if I had a fancy way to say "remove hg section, replace jobs with my-jobs, swap dir and host module and insert new-module after php", a spaceship update (adding new sections somewhere in $SPACESHIP_PROMPT_ORDER will most probably break my setup anyway.

I think there's no alternative but to tell people to manipulate $SPACESHIP_PROMPT_ORDER, some will be lucky and can just append their custom sections, others will completely override $SPACESHIP_PROMPT_ORDER and start watching the changelog for new sections.

---

Also, maybe we are trying to solve a non-existent issue. After all, last time a new section was merged in spaceship-prompt was 10 months ago (in October 2017). I feel it's fine to ask people to check changelog for new sections once a year.

[maximbaz]

And if we all agree that modifying/replacing $SPACESHIP_PROMPT_ORDER should be one and only way to configure prompt order, then my thoughts on the points raised in the first message:

1. I don't think curated lists work very well. Just look at the number of open PRs in oh-my-zsh or spaceship, it takes months to years to get a new section merged. I would rather publish each of my custom sections as a new separate git repo on Github.
2. Having SPACESHIP_CUSTOM_SECTIONS_DIR is a fine idea, that location should take priority over SPACESHIP_ROOT when looking for a section with a certain name (so I can put section named jobs and it will override the default one).

I would probably require SPACESHIP_CUSTOM_SECTIONS_DIR to be a folder that has subfolders with names of the sections, something like that:

~/spaceship-custom-sections/
    jobs/                    # This was cloned from Github
        README.md
        my-jobs.zsh
    new-module/              # This folder I created myself
        my-new-module.zsh

That way those subfolders could be cloned repos from Github.

So instead of this:

https://github.com/denysdovhan/spaceship-prompt/blob/f242c20a044b113b5bbf77bd7d5547742f1018fb/spaceship.zsh#L112-L115

Spaceship would load sections like this:

```
for section in $(spaceship::union $SPACESHIP_PROMPT_ORDER $SPACESHIP_RPROMPT_ORDER); do
if [[ -d "$SPACESHIP_CUSTOM_SECTIONS_DIR/$section" ]]; then
source "$SPACESHIP_ROOT/$section/*.zsh"
else if [[ -f "$SPACESHIP_ROOT/sections/$section.zsh" ]]; then
source "$SPACESHIP_ROOT/sections/$section.zsh"

[olets]

Agreed on all counts. I got caught up in thinking about your puzzles. It _would_ be _cool_ to automatically bring in new sections even after customizing the prompt order, but yeah I don't think the current behavior is a problem. Maybe a feature for 5.0 :)

---

Re: curated lists: yeah, with "lightly curated" I was imagining screening _only_ for malicious code. But maybe just a list of links. And no matter what, this sounds like a side project not part of Spaceship

---

Yeah that's more or less what I was thinking. I've had this in the back of my mind for a while, but talking about it is motivating me to make time to do it. I'll try to get a PR out this weekend

[salmanulfarzy]

This sounds promising :+1: Full support for custom sections would make rarely used section as community sections and we could refine and improve others. Anyway we could make this to v4 ?

// @denysdovhan @nfischer

[denysdovhan]

I agree with @maximbaz's points.

However, I don't really think we need to look up for a folder. I believe declaring new/overriding old section will work completely fine with just declaring custom zsh function. There's no need to source files, we can ask users to source custom sections on their own before using them.

[nfischer]

There's no need to source files, we can ask users to source custom sections on their own before using them.

Fully agree. There are already tools which will download git repos and source files appropriately (ex. zplug). Also, please keep in mind that I don't always want to share my custom sections, so it's easier for me to write it as a function in my .zshrc (which is compatible with the spaceship 3 architecture).