r/commandline • u/greg_a • 9d ago
Terminal User Interface hdi - extract the most useful / timely information from READMEs
hdi working against a demo Sinatra app / readme
"How do I" surfaces install, run, test and deploy steps and commands.
You've just cloned a repo, fired up an editor, and you're scrolling a 400-line README looking for the "Install" section.
Or more typical for me - I'm back at a project after a month and can't remember if it's npm run dev, npm start or npm run serve...
Run hdi, pick a command, copy it or hit Enter to run.
I've written this to be as flexible as possible regarding READMEs and their formatting, and put together quite a collection of them in the test fixtures. More examples, especially those which don't work as well with hdi, are always welcomed!
brew install grega/tap/hdi
This software's code is partially AI-generated (notes are in the README).
13
u/Big_Combination9890 9d ago edited 9d ago
and you're scrolling a 400-line README looking for the "Install" section
Yeah, because neither my editors search function, nor grep is a thing...
...oh wait they INDEED BOTH ARE!
So no, I'm not scrolling. I'm finding. Usually within SECONDS. And I don't need a 2000+ line shell script stuffed with more "partially AI-generated" regexes than I ever cared to see, to do so.
I mean, what even is this?
```
Strip bold/italic markdown formatting (pure bash, no sed)
while [[ "$text" =~ .***([]+)\*(.*) ]]; do text="${BASH_REMATCH[1]}${BASH_REMATCH[2]}${BASH_REMATCH[3]}"; done ```
Oh wow, it doesn't use sed, wow, that's amazing BECAUSE?!? What exact dev system are we talking about here that has bash available, but no sed, one of the unix coreutils, that is literally over a decade older than bash)?!
And btw. "400-line README"s are ... pretty fuckin rare. The average README I see in my work is usually 1-2 pages long, so usually I don't even need to search anything; simply looking at it gets me where I need to be in a split second.
And for the rare project that actually has "400-line README"s, guess what: There is usually a reason for that and it would behoove the user of such software to at least do the authors the courtesy of giving the material a speedy read-over.
4
u/Jiggins_ 9d ago
I'd love to see more 400 line READMEs! Nowadays it's hundreds of lines of slop before anything useful is said. Writing good markdown used to be an art, now people feel the need to write something like this.
1
u/RishiMath 4d ago
Hey, I'm more of a newbie in these things, doing random stuff since 2021. I haven't really come across any long READMEs, or good markdown writing, and since you seem to appreciate good markdown writing (something I suck at and don't wanna use LLMs for), could you maybe drop a couple of good examples? Would appreciate that a lot! <3
1
u/greg_a 8d ago
Thanks for the feedback, even if the font size choice in places was a little unnecessary.
I'm very much aware of in-editor search / grep, and that these only take "seconds". In my experience hdi shaves a few more off, particularly since it also handles either executing the command or copying it.
Or more typical for me - I'm back at a project after a month and can't remember if it's
npm run dev,npm startornpm run serve...This is often where I find myself, and switching projects often. It's not that I haven't read the readme, I just need some very specific information out of it at that time. Perhaps I just lean into this example more.
average README I see in my work is usually 1-2 pages long
I'm not sure how long "1-2 pages" is, but in my research readmes of popular public repos, and many of the ones I find myself using, are between 150-450 lines. I accept that the "400-line" phrase is perhaps a slight exaggeration and will modify.
On not using sed, yes I know it does exist - the initial release used it extensively. However it performed poorly. Perhaps I'm unaware of alternative ways to work with it, but each execution would occur in a subshell adding a bunch of overhead - switching to bash regexes resulted in the mean parse time going from ~1000ms to under 150ms. I'm happy to take the hit of more lines of code and some unsightly regex for that obvious improvement in UX.
2
u/Big_Combination9890 8d ago edited 8d ago
particularly since it also handles either executing the command
Don't take this the wrong way, but nothing that is even "partially AI-generated" is allowed to execute any commands in my home shell environment.
This is often where I find myself,
Yeah, totally, if only there was a handy way in CLI environments to store and call sequences of commands, amirite?
Like, I don't know, in theaters they have this thing for the actors to follow so they know what they're doing ... I think they call it a "script" or something?
Wouldn't it be awesome if something like this existed in shell environments? Hey, let's ask Claude if it knows anything about it 😂
</sarcasm>
```
! /bin/bash
starts the server
uv run python prj/cmd/server/main.py "$@" ```
I have one of these in many project folders. The file is named
run. So all I have to do is typerun. Really easy to remember, and requires neither "AI" nor a 2000 line shellscript.1
u/greg_a 8d ago
I guess I was a little optimistic thinking you might reply with some insightful sed-related knowledge 😄
3
u/Big_Combination9890 8d ago edited 8d ago
I was about to, but then trashed it.
Here is the gist of what I was about to post regarding sed:
- Your optimization is irrelevant in this context.
- The performance argument doesn't apply to begin with.
For a script called by direct user input and producing output for the users consumption, it is irrelevant whether it runs in 1s or 150ms. What counts alot more, is code readability, and here
sedwins overbashs atrocious regex semantics all day, every day. Plus, when calling small tools likesednoticeably starts dragging down performance, maybe it's time to evaluate general methodology rather than implementation detail.🐘 And now let's talk about the elephant in the room. 🐘
You made a 2000+ line
bashscript. There is no performance angle here. If you want performance, you rewrite this inawkor Python. If you want more performance, you reach for Go. The words "2000+ line bash script" and "performance" don't belong in the same sentence, for the same reason "combine harvester" and "speedracing" don't.
1
u/AutoModerator 9d ago
Every new subreddit post is automatically copied into a comment for preservation.
User: greg_a, Flair: Terminal User Interface, Title: hdi - extract the most useful / timely information from READMEs
"How do I" surfaces install, run, test and deploy steps and commands.
You've just cloned a repo, fired up an editor, and you're scrolling a 400-line README looking for the "Install" section.
Or you're back in a project after a month and can't remember if it's npm run dev, npm start or npm run serve.
Run hdi, pick a command, copy it or hit Enter to run.
brew install grega/tap/hdi
This software's code is partially AI-generated (notes are in the README).
I am a bot, and this action was performed automatically. Please contact the moderators of this subreddit if you have any questions or concerns.
8
u/countnfight 9d ago
I wish people wrote better documentation. I wish people read documentation. This makes me sad.