Document metadata format

[stepancheg]

I upgraded stgit, and now zsh prompt does not show current patch.

stgit metadata format changed, so old code reading metadata in zsh no longer works.

code

There are no applied/unapplied files in .git folder now.

AFAIU something like this is needed now:

git show refs/stacks/br:stack.json

Having a document could be helpful.

[jpgrayson]

Thanks for this feedback.

I did not realize that zsh's vcs_info module had StGit support. Good to know!

And yes, the zsh vcs_info module seems to be relying on StGit's old stack metadata which was completely removed in the StGit v1.0 release. The preferred mechanism for zsh to get the stack's applied and unapplied patch lists would be by running stg series --noprefix --applied and stg series --noprefix --unapplied, but if that's too expensive, then inspecting refs/stacks/<branch>:stack.json directly would be okay too, but with the caveat that the current metadata format was introduced in StGit v1.2, and so inspecting stack.json would only work for v1.2 and later. I do expect the current stack metadata format to be stable for the foreseeable future.

I'll also note that StGit ships with its own zsh completions which are up-to-date and far more complete and feature-rich than the completions that zsh ships with. One of these days I need to ask the zsh folks to remove their StGit completions.

I'm going to leave this open as a reminder to improve StGit's user-facing documentation of its stack metadata format.

[jpgrayson]

As a follow-up on this issue, I've contributed a change to zsh that updates its vcs_info to be compatible with StGit versions going back 8-9 years and up to the latest 2.x releases. I would expect this change to be in the zsh release (i.e. whatever comes after zsh 5.9).