Comment by jiggawatts | Hacker News Reader

Comment by jiggawatts | Hacker News Reader

Parent Full thread

This causes a lot of grief for IDEs like Visual Studio, where updating Git breaks the IDE because there is no "API contract". The text output changes, VS fails to parse it, and just crashes out with inscrutable errors.

I've become very opinionated in my old age, and I now firmly believe that:

1. All command-line tools should be "library first, cli second".

2. All text-based formats should include a parser and formatter as a function. Never specify a text format you can't round-trip. In other words, always include an "escape" function and an "unescape" function, or better yet, a parser and serializer. Random config files in Linux are notorious for not doing this. I want to be able to parse them, modify the object in memory, and then write them back out without having to worry about how strings are quoted or dates are formatted.

3. Protocols should always come with a non-executable and machine-readable spec. Think ANTLR grammar file, Open API spec, or something. Never use English only to describe a protocol. Make sure client code can be 100% automatically generated by a tool, in multiple languages.

Is that because they're parsing porcelain output? Or is git's plumbing machine-readable but not well specified?

But git users are more familiar with porcelain so I wouldn't be surprised if they parsed that for an initial implementation.

It sounds like plumbing shouldn't break as often as you imply:

> The interface (input, output, set of options and the semantics) to these low-level commands are meant to be a lot more stable than Porcelain level commands, because these commands are primarily for scripted use.

https://schacon.github.io/git/git.html#_low_level_commands_p...

However, doesn't seem like they're nearly as rigorous as you hope.

> Is that because they're parsing porcelain output? Or is git's plumbing machine-readable but not well specified?

From what I've seen, they're using the latter, but breaking changes are still introduced.

Either way, the output of UNIX-like command-line tools is inherently weakly typed and often completely unspecified.

PowerShell for comparison ships every module as both a user-interactive CLI command (with parameter tab-complete!) and as a programatically usable dynamic library. They're inherently one and the same, there's only one interface that does both. The API returns .NET objects and is strongly typed. There is no parsing step at all. If you load a given version of a library, you'll always get the expected types in the results.

Speaking of which, PowerShell uses semantic versioning for modules and can have multiple running side-by-side.

The future is here, it's just not very evenly distributed.

Semantic versioning still break clients (so what do you mean with multiple versions?). I would say that if you are handed a new version of a binary that spits out text, it is usually much easier to fix that than handling an API with objects.

I have failed to use PowerShell seriously many times, I am always let down by the opaqueness of it. (Which I agree is a common complaint against bash from inexperienced users)

Reply on news.ycombinator.com