feat: add first debug version of gix branch list

[cruessler]

This is a draft PR even though I feel it is already 95 % done. I mainly want to get CI feedback early.

This PR adds gix branch list and gix branch, supporting --all as the only flag.

I copied the way gix tag list and gix tags work, but I’m less sure this is a good idea in this case as passing arguments seems to become trickier. Given the current code, gix branch list --all does not work, but gix branch --all list does which seems sub-optimal to me. What do you think?

[Byron]

Thanks a lot!

Something I'd be interested in learning is what motivates this functionality. Either it helps with debugging possibly by adding specialty features, or it's a long-wanted improvement because it's what you think git branch should have been like. Maybe there are other good reasons for adding a command though, I am open.

Given the current code, gix branch list --all does not work, but gix branch --all list does which seems sub-optimal to me. What do you think?

Indeed, gix branch list --all is better, and I guess one could see if gix branch should auto-list branches.

[cruessler]

The initial motivation for this addition is me trying to oxidize reading branches in gitui. At a high level, I want to make sure both that I understand the API well and that it serves all of gitui’s needs. More specifically, I want to debug how and when special refs, such as origin/HEAD, get resolved to actual branches because in my local gitui branch, I get origin/main twice instead of origin/main once and origin/HEAD once. I hope this is an acceptable motivation. :-)

[Byron]

Let's add the "getting acquainted with the API" to the list of great motivations :) - something I want to avoid is to have these subcommand 'just because'.

Regarding the origin/HEAD being auto-resolved - I wouldn't expect that, it should list it as ordinary ref and its target() would be a symbolic reference (usually), that has to be resolved in a separate step.

[cruessler]

Let's add the "getting acquainted with the API" to the list of great motivations :) - something I want to avoid is to have these subcommand 'just because'.

To add a bit of context/background: another motivation creating this (and similar) PRs is having a minimal working reference implementation of a certain set of APIs. In my experience, there are so many overlapping and intertwined concepts in the git space that, when I start working an a new area, I often miss simple examples that allow me to discover how the different layers interact. I really like that gitoxide’s APIs expose a lot of the underlying concepts in a very nuanced and well documented way, but I find it harder to figure out how to tie them together in order to implement certain higher-level APIs, something which happens quite often when I work on gitui. I also like to compare gitoxide’s APIs to git2’s, so I can suggest additions/minor changes when I see an opportunity.

Regarding the origin/HEAD being auto-resolved - I wouldn't expect that, it should list it as ordinary ref and its target() would be a symbolic reference (usually), that has to be resolved in a separate step.

This was me setting myself a trap, basically. :-) In the code that was causing the ”issue”, I had a .peel_to_commit() that resolved origin/HEAD to origin/main before I accessed the reference’s name, so I just hadn’t properly taken into account that .peel_to_commit() is, in fact, a mutating method. I learned something new that way, though. :-)

[Byron]

I also like to compare gitoxide’s APIs to git2’s, so I can suggest additions/minor changes when I see an opportunity.

Loving that! And like always, the git2 doc comment aliasing might not be setup everywhere where it should be. Additionally, I could imagine extra paragraphs that explain differences to the respective git2 implementation (if that makes sense), just for a chance that others won't feel the same pain.

I learned something new that way, though. :-)

This probably means a fix is in order. There are other functions like it that are called …_in_place() and maybe the same should be done here. You could deprecate the old name and link it up with the new name.

[Byron]

Thanks, this works!

I also learned that pub mod x {}; fn x() {} are perfectly valid, and I never ever did that myself for some reason. Definitely learned something and think this a pattern to repeat.

Regarding the "I missed this during my review", I certainly should have been more specific as it's a copy-paste bug you also seem to have missed when marking it done :D.

[cruessler]

Regarding the "I missed this during my review", I certainly should have been more specific as it's a copy-paste bug you also seem to have missed when marking it done :D.

Absolutely! :-D I was so convinced that the comment was a duplicate of another one that I didn’t read it carefully enough.