These example commits seem like pretty bad commit messages to me. They are just a summery of the changes (something a motivated reader can rediscover by reading the diff), while leaving out the why, which will be lost to history if not documented.
Yes, the why is very very important, but imo it's also useful with a one-liner summary of the actual change.
Consider a trivial change but affecting tens of places in the code, eg an API change. It's very useful to be able to quickly glance past "use new abc-API; required since dependency X bumped to Y" and mentally move on, rather than actually having eyes scanning over those actual changes.
I disagree with it being a minor issue. If I write a shell script around a program that accepts GNU-style arguments, I expect the following to be correct:
./cmd -a"$USER_CONTROLLED_DATA"
A program using this package would break that assumption, introducing a bug where this user-controlled data cannot start with an '='.
This syntax is supported by argparse and clap, the most popular argument parsers for Python and Rust respectively, and it seems to have caused almost no problems for them. It's a problem for the uutils implementation of cut, since `cut -d=` is common, but that's the only instance I could find after a long time scouring search engines and bug trackers and asking for examples.
If anyone does know of other examples or other places this has been discussed I'd love to hear it though, maybe I just haven't found them.
(Also, the more reliable way to write this in general is `-a "$USER_CONTROLLED_DATA"`, since that'll behave correctly if $USER_CONTROLLED_DATA is empty. As will `-a="$USER_CONTROLLED_DATA"` if you know the command supports it.)
In the Gentoo world, sometimes you need to give an exact package name which looks like `=net-misc/foo-0.1.2-r1`. The exact match has to start with the '='.
I think short options taking a value in the same argv (i.e. `-o=1` stuff) isn't a GNUism mostly because it's backwards-incompatible with POSIX. `=` is a valid getopt option character, `chmod` uses it.
That said, I think? 'nloomans means for USER_CONTROLLED_DATA to be a set of short flags, not flag values, as in:
root@08e9950d5bfd:/# export USER_CONTROLLED_DATA=lh
root@08e9950d5bfd:/# ls -a"$USER_CONTROLLED_DATA"
total 56K
drwxr-xr-x 1 root root 4.0K Mar 23 16:51 .
drwxr-xr-x 1 root root 4.0K Mar 23 16:51 ..
[...]
Not that I've seen this in the wild before. But everyone's use of bash is a unique personal hell anyway.
Anyway, one other alternative for the `cut` situation is to allow either ':' or '=' to optionally separate the key and the value. Then you can say `cut -d:=` or `cut -d=:` if you wanted to use either one. This is what https://github.com/c-blake/cligen does (for Nim, not Go).
The problem is existing shell scripts and muscle memory and command histories. `cut -d=` has always worked and works on all the other implementations so it should keep working if you switch to uutils.
Literally any short option key that takes a string or a char that could legitimately start with '=' has the problem, though, not just `cut`. The '=' will be "eaten" by one tool and left in another. But you know that. You write a bit as if we disagree, but I don't see any real point of contention. :-) Also, uutils has a very strict "drop-in" agenda. So, as another e.g., if you want `cp -t=foo` or `cp -S=foo` to work the same, you're going to have trouble if that '=' is eaten.
So, in this case that would seem to imply a problem for any utilities with options taking strings-or-chars, not merely `cut -d`. If uutils really wants to be strictly drop-in compatible, they may well need to roll their own option parser or twist the arm of whoever's they use to provide a mode for them.
In the more general case, "cross compatibility" may just always be limited by the reality that people just disagree on this stuff "more than they seem to think they do" (at least in my experience) and definitely more than they wish they did. I surveyed my /usr/bin once and like half of thousands of commands did not work with --help (yes, running that took some confidence in backups! but anyone could replicate on a throwaway VM or something). Consistency is nice, but consistency with what? -l=foo is consistent with --long=foo, but not (some, but not other) historical things.
I'm not sure there will ever will be a world in which you don't need to know which PLang/CL toolkit was used to make a CLI utility if you really want to know its syntax. The article's lib is going its own way from the Go stdlib. POSIX is pretty darn calcified. A 15 year old Python stdlib thing is unlikely to ever change in this regard. Python also allows "--beg" for "--beginning-long-option" if nothing else starts with "--beg" even back in its optparse days and that also tends to be controversial. cligen tools actually provide a --help-syntax. Maybe something like that could take off?
I can think of a lot of cases where it theoretically could be a problem, but `cut -d=` is the only one I've found so far where an end user ran into trouble because of this ambiguity, and I think it's the only one for which uutils bothers implementing a workaround. That's why I give it special attention.
> You write a bit as if we disagree, but I don't see any real point of contention. :-)
The `cut -d:=` spelling solves a different problem than the one I meant (and the one you're now talking about). But we're mostly on the same page!
It is safer to just put in the space (much like you put in the quotes to be safe). Python's argparse will also accept but not require an `=` separator (maybe optparse, too - I haven't checked that one).
It's only "safer" because argp has this particular bug. It's safer for argp (or python's argument parser, for that matter) to not have surprising buggy features like this.
While it may go against your personal expectations, I believe at least the Python variant is intentional not an accidental/unintended "bug".
"Surprise" is observer-relative. From a blank slate, if --long=val and --long val both work, then why not -s=val and -sval and -s val for a short -s?
So, I think the right word here is "disagreement" (perhaps about "which consistency - history vs. internal"), not throwing shade by simply declaring/asserting it a "bug".
I think because Claude said so and the author just copied it without checking. You can see it in the first screenshot of Claude's output:
> After examining the provided code, I've determined that this appears to be a CLI application for Claude code-related functionality, built as a CommonJS TypeScript application that has been compiled with webpack.
I tested the example using the TalkBack screenreader on Android. With Firefox I was able to select and click on the link, but it did not announce the email address. With Chromium it completely ignored the existence of the SVG email. I was unable to select it and it was like the email wasn't there at all.
I agree! Showing a bit of the markdown in the rendered text really gives the page a nice hacky feel. I'm doing something similar on my website[1] but this blog looks a lot nicer then mine!
The biggest problem on my version I think is that links aren't obvious enough in dark mode, but I like the links used here so I'll look into that.
[1]: https://noahloomans.com/tutorials/makefile/ (The contents of this page is intended for the other students at my college and probably doesn't make a lot of sense standalone)
