feature: ls dump issues as plaintext (markdown/org-mode)
Labels: area/clienhancement
Timeline
karlicoss (karlicoss) opened (edited)
Basically a command like git bug dump that would dump the issues rendered as a single markdown/org-mode file (or a directory of files). This would allow to instantly search in issues within the IDE without having to switch to the terminal/web UI.
Previously I was using org-sync for this, but just discovered git bug, and it seems way more mature and reasonable :)
Format is not super important, IMO just merely having it as text gives you 90% of the benefits regardless the format, but:
markdown would be easier to support natively since github uses it
org-mode is kinda nice because you can use map github's tags and states (open/closed).
Possible future improvements:
dump plaintext automatically on git bug bridge pull
allow two way sync, i.e. modifying comments, adding new issues by adding new entries to text files... but that seems hard and maybe not worth it
Let me know if you think it makes sense, and if you have any thoughts on possible implementation, I would be happy to contribute. And thanks for this awesome tool :)
Michael Muré (MichaelMure) commented (edited)
Hoooo, I like this idea of org-mode. I'm not so familiar with it though, could you provide an example with all kind of relevant features ?
Yes, git-bug would benefit from having this kind of export. It has been touched on in #45 and #370.
In term of UX I'm a bit unsure what is the good way forward. It could be:
a flag of the ls command to change the output style
a new export command
As this new feature would share basically everything ls does to do the filtering, I think it make more sense to just add flags there to change the output (it could also be done with other commands). So let's add:
--json
--orgmode
--markdown
--plain (just the list of bugs, one title per line)
--csv
dump plaintext automatically on git bug bridge pull
I would leave that to scripting, that's what those CLI commands are for.
allow two way sync, i.e. modifying comments, adding new issues by adding new entries to text files... but that seems hard and maybe not worth it
Yeah, probably not worth it. Far too complex for what it would bring.
Michael Muré (MichaelMure) changed the title from feature: ls dump issues as plaintext (markdown/org-mode) to feature: ls dump issues as plaintext (markdown/org-mode)
Michael Muré (MichaelMure) commented
Let me know if you think it makes sense, and if you have any thoughts on possible implementation, I would be happy to contribute.
Yes please ;-)
In term of implementation, it'd be nice if the ls command could do the listing/loading of bugs (as currently) and delegate the output to a set of formatters, one for each supported format.
Michael Muré (MichaelMure)
added label
area/cli
Michael Muré (MichaelMure)
added label
enhancement
karlicoss (karlicoss) commented
I'm not so familiar with it though, could you provide an example with all kind of relevant features ?
Absolutely, quickly sketched an example how it could look (in my Emacs):
outlines are easy to collapse and navigate, you can easily jump between the comments
links are clickable: #392 would bring you to the issue, X links straight to the comment
the dates in org-mode they are are first class objects (e.g. you can easily query for something like "all comments in the past week")
the tags on the right, separated by colons. In org-mode, it's easy to filter by tags and search globally over them
It's even possible to support internal links, e.g. if someone linked to another issue in the same project, you can have an org-mode link that would jump within the file (rather than go to the web interface)
markup: org-mode supports all the reasonable markup: links/bold/verbatim, etc., but the easiest is to "quote" the comments, at least to start with, so we don't have to deal with escaping transforming from markdown, etc.
Here's how the raw isues.org file looks:
#+TODO: OPEN | CLOSED
# issues are listed on the top level
* OPEN [2020-05-23 Sat 13:00] [[https://github.com/MichaelMure/git-bug/issues/392][#392]] karlicoss: feature: ls dump issues as plaintext (markdown/org-mode) :CLI:enhancement:
# each comment could be a subitem
** [2020-05-23 Sat 13:00] [[https://github.com/MichaelMure/git-bug/issues/392#issue-623624779][X]] karlicoss: Basically a command like...
...
** [2020-05-23 Sat 13:00] [[https://github.com/MichaelMure/git-bug/issues/392#issuecomment-633037002][X]] MichaelMure: Hoooo, I like this idea of org-mode
: Hoooo, I like this idea of org-mode. I'm not so familiar with it though, could you provide an example with all kind of relevant features ?
:
: Yes, git-bug would benefit from having this kind of export. It has been touched on in #45 and #370.'m not so familiar with it though, could you provide an example with all kind of relevant features ?
* CLOSED [2020-03-16 Mon 14:05] [[https://github.com/MichaelMure/git-bug/issues/360][#360]] mkroehert: git-bug GitLab bridge does not correctly import labels :bridge:bug:
: I heard of git-bug a couple of days ago and gave it a try today.
: But first of all, I'd like to thank you for creating and maintaining this great project.
# .... more issues below
As you can see it's not that different from markdown in terms of structure, just supports more features. Once we have an abstract 'tree' of issues and comments, supporting different syntax should be a matter of few tweaks, hopefully.
I would leave that to scripting, that's what those CLI commands are for.
yeah, fair enough.. thinking again about it, git fetch hook might be better suited for this
In term of implementation, it'd be nice if the ls command could do the listing/loading of bugs (as currently) and delegate the output to a set of formatters, one for each supported format.
Cool! Thanks, I'll take a look.
Michael Muré (MichaelMure) commented
@Invincibot is working on this :tada:
Michael Muré (MichaelMure) commented
https://github.com/MichaelMure/git-bug/pull/403 merged with support for git bug ls --format=<format>. Supported values are default, plain and json at the moment. orgmode is coming, as well as others commands enabled the same way.
@karlicoss if you could keep an eye on that and test what @Invincibot is going to write for orgmode, that would be very helpful.
Vincent Tiu (vincetiu8) commented (edited)
@karlicoss just wondering what you think should be the output style for markdown from a design perspective. I was thinking an issue could look like this:
but would be extremely grateful for any potential suggestions that could improve the readability/utility of the markdown. I'm implementing the org-mode in the same format as you requested!
karlicoss (karlicoss) commented
Looks good, thanks! Few things from my perspective:
might be nice to have status in the heading for a quick overview?
instead of login: could use clickable links instead?
not sure if the ids are worth including in the markdown, can they even be reached through github's interface? Also human id seems to be a prefix of id, so not sure if worth keeping?
Vincent Tiu (vincetiu8) commented (edited)
Unfortunately, git-bug users aren't directly linked to Github, and no information about Github users is stored in git-bug, so the second wouldn;t be possible.
How does this look instead?
Ah, makes sense. Although it does know origin:github so perhaps in the future some fine tuning with origin-specific links could be added.
Yeah, I think it looks good! Perhaps best to also ask someone who's more used to working with Markdown, but I guess in any case it's easy to change in the future (since the dump is meant to be read only). As long as it's something one can easily search over from the text editor, it's great regardless the minor details :)
Vincent Tiu (vincetiu8) commented
Oh and one other thing: @karlicoss I don't believe it is possible to obtain the comments from a bugExcerpt or get a list of all the bug snapshots, so it may not be possible to display the comments of the bugs using the ls command. @MichaelMure will have to fact-check me on that but atm may not be able to access comments using ls.
Michael Muré (MichaelMure) commented
Oh and one other thing: @karlicoss I don't believe it is possible to obtain the comments from a bugExcerpt or get a list of all the bug snapshots, so it may not be possible to display the comments of the bugs using the ls command. @MichaelMure will have to fact-check me on that but atm may not be able to access comments using ls.
It's possible, you can just load the full Snapshot and read the comment from there. But that should not be done really. ls is a command to list bugs and get an overview. You should only get the most important information, that is what is stored in the excerpt already. Displaying more details about a bug make more sense in the show command.
Now, while org-mode make total sense to me as a way to export bugs to another format, I don't see the point of this markdown thing. What are we trying to solve here really? We need to answer that question properly to see if 1) it's worth it and 2) what and how this feature should really do. So @karlicoss what's the point for you?
Main usecase for me personally is being able to quickly search throughout the issues without always going to github, or even having git-bug open for the specific repository. Ideally I'd set up a pull hook to run something like git-bug ls --format org-mode > issues.org, so the issues are somewhat up to date. I'd prefer to have all discussions in this file, but if it goes against the idea of what ls command should do (i.e. an overview) -- I'm okay for now, even having the titles and being able to quickly jump to the specific bug on github is already really great. Maybe later we can reconsider it, or add another mode, etc :)
With regards to Markdown -- I'm fairly indifferent about markdown vs org-mode in general for such scenarios (i.e. a read-only plaintext dump), but org-mode has better builtin primitives for working with structured data. For Markdown -- even if we come up with some custom format, not sure if there is much point if no tools support it. And if you don't get any primitives (tags/states/dates), you could as well just use .org file, it's plaintext too.
Michael Muré (MichaelMure) commented (edited)
Vincent Tiu (vincetiu8) commented (edited)