v1.0 / The Future

[jimeh]

It's a bit of an understatement that I've mostly ignored this project for the last few years. I haven't personally used git-aware-prompt since I switched from bash to zsh about 5 years ago. And the project was always a bit of quickly put together hack.

However due how much attention it's getting as of late, I want to try to make a more decent effort at it. Lots of people have created their own forks with tweaks and new features, some of which I'd like to incorporate in this "rewrite".

This issue will serve as a initial planning session of the overall goals of this update/rewrite. As such if you're reading this and have anything you'd like to add, please do leave a comment :)

Below is the initial rough draft list of goals in no specific order:

• [ ] Make the prompt fully customizable. Using environment variables to define prefix/suffix, tag prefix/suffix, dirty characters, and more to allow you to fully customize exactly how the git information looks.
• [ ] Officially support zsh. This includes the ability to install git-aware-prompt as a plugin for oh-my-zsh, antigen, zgen, zplug, etc. This will allow me to personally use the project again.
• [ ] Be compatible with oh-my-zsh themes. Allows people who use oh-my-zsh's git plugin and a oh-my-zsh theme to just swap out the git plugin for git-aware-prompt.
• [ ] Fancier dirty tracking. Ability to show the number of modified/untracked/staged files, etc.
• [ ] Retain backwards compatibility as much as possible (for now).
• [ ] Start using semantic versioning.
• [ ] Unit tests?
• [ ] Look at git's own __git_ps1 thing via git-prompt.sh. I've never looked at it, so no clue if it's of any use to us. Also if it is of use, do we want to depend on it, internalize it, or simply have our own implementation like right now to keep dependencies at zero.
• [ ] Deal with timeouts. Sometimes the git dirty status check takes a long time first time around for very large repos. Having some kind of timeout might be a good idea. Overall requires more research.
• [ ] Keep the code very clean and lean, typically not having any code running that the end user doesn't specifically use. This could be done with if statements (but it means if statements run), or potentially through code generation.
• [ ] Modular design. Related to clean code above. Basically it means features are separate files in source, and the scripts that are used are built from all of the modules. This should give us a flexible base to work with, and it means those who wish can create custom builds with only the modules/features they want.
• [ ] Indicate if current branch has a upstream branch or not.

[mikeweilgart]

Great!

One thing about zsh support: I want to keep the script logic very lightweight, as after all it runs every single time I hit "enter" in my shell. I personally don't use zsh, so:

I would like it as a design goal that at any time, you could download the current tip of "master" onto a fresh box, delete the script files for any shells you are not using (and possibly change one line of one file), and have a clean, no-cruft "git aware prompt" with no evidence that it was ever intended for other shells than your own (whether bash, zsh or other).

A secondary stronger version of this design goal: That any aspect of the customization that the user doesn't intend to use can be diked out, line by line, without requiring any edited lines, only removed lines. :)

This may not be 100% attainable but for most cases I think it will be, and I think it's a worthy design goal. (It also may have the side benefit of reducing complex merge conflicts when incorporating users' individual improvements.)

[mikeweilgart]

Also, I think before any serious work is done to integrate the code from our various forks, we should make an effort to lay out the interface documentation. Specifically, if we created a well-thought-out "readme" with a description of features and how to use/customize the prompt, we could then sort out the top-level design and avoid writing code that would be hard to customize later. (This needn't take a long time.) Perhaps we could do that in the Wiki?

[mikeweilgart]

One possible implementation, by the way, would be to write the customizing code as a code generator rather than a logic-heavy prompt script. You would choose a shell, choose colors, etc., and the code would output a very small, lightweight shell function definition to be added to your PROMPT_COMMAND, along with appropriate color variable definitions so the whole thing could be sourced from your favorite shell's .*rc file.

[joeytwiddle]

Interesting goals @mikeweilgart. I imagine you're suggesting a reusable library and a file for each shell with that shell's specific concerns in it. Sounds like a worthy goal, and should be possible with hardly any more complexity than we have now. Also interesting goal about the "diking".

But apart from bash and zsh (which thankfully share a lot of syntax, if no options), what shells would you be interested in supporting? The only one I can think of that is popular is fish, but that has a significantly different syntax, so a fish-compatible script might be a little overambitious.

@jimeh all of your suggestions seem worthwhile, but it might be worth waiting to see if there really is demand for them. (It's possible that users are quite happy with what you've given them already, or with what the alternatives provide.)

+1 for checking out the official __git_ps1 script. It seems to be doing things we had never even considered!

Unsurprisingly I'm going to raise timeout as an issue! A few people have reported an unresponsive prompt when first entering a heavy repo. It is difficult to solve that problem cleanly but I think it might be one of the more desired improvements (again, research needed). An untidy solution like mine might dash @mikeweilgart's hopes of a clean lean script. ;) (You could use /usr/bin/timeout quite cleanly to kill git status if it runs for too long, but I dropped that because I really wanted to let it continue running in the background.)

Realistically, I probably won't help you much with this. I'll be tweaking my branch(es) now and then, and as always you are welcome to use whatever you fancy from there.

One thing I feel is still missing from my version: A nice subtle way to indicate whether the current branch has an active upstream/remote, or has no tracking branch at all. At the moment these two situations look identical (if you are up-to-date with the upstream). One possibility is to display (branchname) for untracked and [branchname] for a tracked branch. I have done that now.

[jimeh]

@mikeweilgart I agree with all of your points. As for the bash/zsh stuff, they would share the same functions, and would only really differ with how modify the prompt. I do like having the ability to just download a specific file from the repo for your shell and calling it done. And I like the idea of code generation too.

So off the top of my head, I'd go for a modular design, where each feature is technically a separate file, and we have pre-defined "standard" builds (taking the form of a single self-contained file) for bash, zsh, etc. which are checked into the repo. If someone like you wants to completely strip out features they don't use, they could simply clone the repo and run the builder script themselves with custom options to strip out stuff they don't want. This allows ease of use to stay pretty much straight forward, but people who want to customize it can do so easily :)

Regarding your suggestion to first put together some docs to nail the design before just bashing out some code, I completely agree. I'm planning on putting together a new rough draft readme in a branch this week, and maybe we can take it from there?

[jimeh]

@joeytwiddle Maybe the list of features is a little long, but it is a rough draft. Also most of them are things I'd personally want so it fits in with my setup.

And don't worry, I wasn't expecting any serious help, mostly was just hoping you guys would have some spare time to dump your thoughts a bit as you've spent more time with this than I have.

Indicating if there's a upstream branch or not is a good idea I think, so I've added it to the list of goals for now.

Regarding other shells, I think focusing on bash and zsh is good enough for now. If another sh-like shell can be supported using the same code and little effort, that might be worth it. As for fish, I'm pretty sure it'd have to a completely separate codebase mirroring features between the two. As I don't use fish myself, I'd say fish support is out of scope for at least until we have a solid 1.0 base.