[GH-ISSUE #362] CLI convention: --version-semver #1135

New Issue

GiteaMirror · 2026-04-16T10:23:36-05:00

GiteaMirror commented

2026-04-16 10:23:36 -05:00

Originally created by @AloisMahdal on GitHub (Apr 6, 2017).
Original GitHub issue: https://github.com/semver/semver/issues/362

Note: this is not intended as suggestion to change SemVer but rather as convention for people who already use SemVer and want to make as much use of it as possible.

Problem

It's a well-known convention for CLI tools to include --version option that only causes the program to report its version and exit. It's not so common, however, to have the version information in predictable format. For example:

$ python --version
Python 2.7.13
$ tr --version
tr (GNU coreutils) 8.25
Copyright (C) 2016 Free Software Foundation, Inc.
License GPLv3+: GNU GPL version 3 or later <http://gnu.org/licenses/gpl.html>.
This is free software: you are free to change and redistribute it.
There is NO WARRANTY, to the extent permitted by law.

Written by Jim Meyering.
$ curl --version
curl 7.51.0 (x86_64-redhat-linux-gnu) libcurl/7.51.0 NSS/3.27 zlib/1.2.8 libidn2/0.16 libpsl/0.17.0 (+libidn2/0.11) libssh2/1.8.0 nghttp2/1.13.0
Protocols: dict file ftp ftps gopher http https imap imaps ldap ldaps pop3 pop3s rtsp scp sftp smb smbs smtp smtps telnet tftp 
Features: AsynchDNS IDN IPv6 Largefile GSS-API Kerberos SPNEGO NTLM NTLM_WB SSL libz HTTP2 UnixSockets Metalink PSL 
$

Having extra info in the text may be useful but unless common format is kept, it's hard to consume the version number by scripts such as test harnesses or management tools.

Convention

Now some authors may decide to be more cooperative by implementing SemVer. These will obviously show SemVer-compatible version in the text. A nice convention would be to provide also option --version-semver, which would be guarranteed to ouput only the SemVer-compatible version and nothing else. This option would normally accompany the "traditional" --version option, which could still include extra "free form" detail.

Usage

Scripts intending to use other CLI tool versions could then use code such as:

version=$(tool --version-semver)
test -n "$version" || {
    version=$(some_tool_specific_parsing)
}

Originally created by @AloisMahdal on GitHub (Apr 6, 2017). Original GitHub issue: https://github.com/semver/semver/issues/362 **Note:** this is not intended as suggestion to change SemVer but rather as convention for people who already use SemVer and want to make as much use of it as possible. Problem ===== It's a well-known convention for CLI tools to include `--version` option that only causes the program to report its version and exit. It's not so common, however, to have the version information in predictable format. For example: $ python --version Python 2.7.13 $ tr --version tr (GNU coreutils) 8.25 Copyright (C) 2016 Free Software Foundation, Inc. License GPLv3+: GNU GPL version 3 or later <http://gnu.org/licenses/gpl.html>. This is free software: you are free to change and redistribute it. There is NO WARRANTY, to the extent permitted by law. Written by Jim Meyering. $ curl --version curl 7.51.0 (x86_64-redhat-linux-gnu) libcurl/7.51.0 NSS/3.27 zlib/1.2.8 libidn2/0.16 libpsl/0.17.0 (+libidn2/0.11) libssh2/1.8.0 nghttp2/1.13.0 Protocols: dict file ftp ftps gopher http https imap imaps ldap ldaps pop3 pop3s rtsp scp sftp smb smbs smtp smtps telnet tftp Features: AsynchDNS IDN IPv6 Largefile GSS-API Kerberos SPNEGO NTLM NTLM_WB SSL libz HTTP2 UnixSockets Metalink PSL $ Having extra info in the text may be useful but unless common format is kept, it's hard to consume the version number by scripts such as test harnesses or management tools. Convention ======= Now some authors may decide to be more cooperative by implementing SemVer. These will obviously show SemVer-compatible version in the text. A nice convention would be to provide also option `--version-semver`, which would be guarranteed to ouput *only the SemVer-compatible version* and nothing else. This option would normally accompany the "traditional" `--version` option, which could still include extra "free form" detail. Usage ==== Scripts intending to use other CLI tool versions could then use code such as: version=$(tool --version-semver) test -n "$version" || { version=$(some_tool_specific_parsing) }

GiteaMirror added the question label 2026-04-16 10:23:36 -05:00

GiteaMirror closed this issue

2026-04-16 10:23:36 -05:00

GiteaMirror commented

2026-04-16 10:23:37 -05:00

@zafarkhaja commented on GitHub (Apr 7, 2017):

--version-semver, isn't it a duplication, how about --semver?

@zafarkhaja commented on GitHub (Apr 7, 2017): --**ver**sion-sem**ver**, isn't it a duplication, how about --semver?

GiteaMirror commented

2026-04-16 10:23:38 -05:00

@AloisMahdal commented on GitHub (Apr 7, 2017):

It's intended to be subset of the --version namespace. Version info is a very specific type of meta-data, so it's natural to have specific way of getting it. Also it's not really intended for humans (e. g. in interactive mode) so there's no real need to keep it short.

Calling it --semver is problematic. semver is IMO way too short to be recommendable for "all CLI tools in general". It might not sound probable but this particular cluster of six letters could have already other, completely unrelated meaning: "version" is not the only word starting with "ver" and "sem" is not the only word starting with "sem", and that's just one way of splitting it.

A special case of this could be a tool which actually works in the domain of version information and management. Such tool could naturally already use this switch (or want to keep the option to use it for later).

This gets even worse when you realize that SemVer is not the only versioning standard out there. This convention could be pretty easily extended to any number of other versioning standards. But changing the convention to use the name directly breaks this extensibility.

(Also, you are a bit mixing apples with oranges here. It's no more duplication than phrase "SemVer version": both "version" and "semver" have different meaning; they rather specify each other rather than just repeat.)

@AloisMahdal commented on GitHub (Apr 7, 2017): It's intended to be subset of the `--version` namespace. Version info is a very specific type of meta-data, so it's natural to have specific way of getting it. Also it's not really intended for humans (e. g. in interactive mode) so there's no real need to keep it short. Calling it `--semver` is problematic. `semver` is IMO way too short to be recommendable for "all CLI tools in general". It might not sound probable but this particular cluster of six letters could have already other, completely unrelated meaning: "version" is not the only word starting with "ver" and "sem" is not the only word starting with "sem", and that's just one way of splitting it. A special case of this could be a tool which actually works in the domain of version information and management. Such tool could naturally already use this switch (or want to keep the option to use it for later). This gets even worse when you realize that SemVer is not the only versioning standard out there. This convention could be pretty easily extended to any number of other versioning standards. But changing the convention to use the name *directly* breaks this extensibility. (Also, you are a bit mixing apples with oranges here. It's no more duplication than phrase "SemVer version": both "version" and "semver" have different meaning; they rather *specify* each other rather than just repeat.)

GiteaMirror commented

2026-04-16 10:23:38 -05:00

@FichteFoll commented on GitHub (Apr 7, 2017):

Just make it - - semantic-version imo. I wanted to comment on the overall proposal as well, but lack the time currently.

@FichteFoll commented on GitHub (Apr 7, 2017): Just make it - - semantic-version imo. I wanted to comment on the overall proposal as well, but lack the time currently.

GiteaMirror commented

2026-04-16 10:23:40 -05:00

@AloisMahdal commented on GitHub (Apr 8, 2017):

@FichteFoll Thanks for the comment but it does not seem convincing. You don't seem to reveal much about reasoning behind why "--semantic-version" would be better than my proposal "--version-semver". As I said in last comment, it's intentional to make it subset of the existing well-known namespace.

@AloisMahdal commented on GitHub (Apr 8, 2017): @FichteFoll Thanks for the comment but it does not seem convincing. You don't seem to reveal much about reasoning behind why "--semantic-version" would be better than my proposal "--version-semver". As I said in last comment, it's intentional to make it *subset* of the existing well-known namespace.

GiteaMirror commented

2026-04-16 10:23:41 -05:00

@krzysiekpiasecki commented on GitHub (Apr 8, 2017):

@AloisMahdal IMO the convention you are proposing is a bad idea. You propose an additional interface to return version information. Simplicity is achieved by removing interfaces rather than adding more in the name of greater flexibility. In addition, the presented script assumes that we take action according to the full version. This does not include components that will still need to be parsed anyway.

In sum. We have one --version interface. Sometimes it will be a semantic implementation, sometimes it will not. This is a convention. If someone wants more, he will designate himself.

@krzysiekpiasecki commented on GitHub (Apr 8, 2017): @AloisMahdal IMO the convention you are proposing is a bad idea. You propose an additional interface to return version information. Simplicity is achieved by removing interfaces rather than adding more in the name of greater flexibility. In addition, the presented script assumes that we take action according to the full version. This does not include components that will still need to be parsed anyway. In sum. We have one ```--version``` interface. Sometimes it will be a semantic implementation, sometimes it will not. This is a ```convention```. If someone wants more, he will designate himself.

GiteaMirror commented

2026-04-16 10:23:43 -05:00

@AloisMahdal commented on GitHub (Apr 10, 2017):

@krzysiekpiasecki I agree that the less is better. This is actually meant for people who want more but rather than everyone come up with own spelling (--semver, --semantic-version), the "less" is in offering universal spelling that could work for all. So in its way this is application of the same principle.

About the "want more": the main motivation for this was in context of automated testing. I was developing a test harness and I wanted to show version of the tested module as part of the log, but keep the parsing code as trivial as possible (as every test-related code should strive for) without sacrificing the conventional --version which I already used for human-readable information. It's worth noting that there was already assumption that the version itself does say enough; if that's not the case, you will indeed designate yourself.

(That said, your comment did make me think a bit more critical about this proposal.)

@AloisMahdal commented on GitHub (Apr 10, 2017): @krzysiekpiasecki I agree that the less is better. This is actually meant for people who *want more* but rather than everyone come up with own spelling (`--semver`, `--semantic-version`), the "less" is in offering universal spelling that could work for all. So in its way this is application of the same principle. About the "want more": the main motivation for this was in context of automated testing. I was developing a test harness and I wanted to show version of the tested module as part of the log, but keep the parsing code as trivial as possible (as every test-related code should strive for) without sacrificing the conventional `--version` which I already used for human-readable information. It's worth noting that there was already assumption that the version itself does say enough; if that's not the case, you will indeed designate yourself. (That said, your comment did make me think a bit more critical about this proposal.)

GiteaMirror commented

2026-04-16 10:23:44 -05:00

@jwdonahue commented on GitHub (Nov 28, 2017):

This is an interesting idea that belongs to the realm of things that layer on top of SemVer. Until such layers are established and adopted, there is no point in attempting to be proscriptive from within the SemVer spec. Let's let SemVer be one simple node in the web of evolving dev-ops standards, keep it simple, but not too simple.

I vote to close this issue.

@jwdonahue commented on GitHub (Nov 28, 2017): This is an interesting idea that belongs to the realm of things that layer on top of SemVer. Until such layers are established and adopted, there is no point in attempting to be proscriptive from within the SemVer spec. Let's let SemVer be one simple node in the web of evolving dev-ops standards, keep it simple, but not too simple. I vote to close this issue.

GiteaMirror commented

2026-04-16 10:23:45 -05:00

@AloisMahdal commented on GitHub (Nov 28, 2017):

@jwdonahue See Note in the header of the original post. By any stretch, this was never intended to be part of SemVer. Original SemVer points to this issue tracker as a means to "leave feedback" and as you can see, the tracker has been already used for many years as medium for discussions about both SemVer and conventions built above it.

@AloisMahdal commented on GitHub (Nov 28, 2017): @jwdonahue See Note in the header of the original post. By any stretch, this was never intended to be part of SemVer. Original SemVer points to this issue tracker as a means to "leave feedback" and as you can see, the tracker has been already used for many years as medium for discussions about both SemVer and conventions built above it.

GiteaMirror commented

2026-04-16 10:23:46 -05:00

@jwdonahue commented on GitHub (Nov 28, 2017):

@AloisMahdal, what/where is this "Original SemVer"? Please forgive my ignorance, I am still stumbling around a bit here at GitHub. When I see open issues, I see technical debt and have a strong desire to drive it to zero. I am all for drawing attention here to other sites and ideas, I just don't see the point in leaving this on the list of SemVer open issues. Until I chimed in, there has been no activity on this issue since April.

@jwdonahue commented on GitHub (Nov 28, 2017): @AloisMahdal, what/where is this "Original SemVer"? Please forgive my ignorance, I am still stumbling around a bit here at GitHub. When I see open issues, I see technical debt and have a strong desire to drive it to zero. I am all for drawing attention here to other sites and ideas, I just don't see the point in leaving this on the list of SemVer open issues. Until I chimed in, there has been no activity on this issue since April.

GiteaMirror commented

2026-04-16 10:23:46 -05:00

@AloisMahdal commented on GitHub (Nov 28, 2017):

@jwdonahue welcome to GitHub. Good spirit is welcome, but please note that this is a very diverse communty with very diverse practices; basically each project can have its own rules. So don't fall into the illusion that the only reason for an issue being open (and inactive) is because people forgot about it. It's perfectly OK for an issue to be open for years; not all issues represent a technical debt.

Generally, people will be happy if you want to contribute to their project but they will want you to get familiar with contributing guidelines first. (If an issue is affecting you, though, it's OK to just politely ask about the state :-)).

(Note: I'm not even representing community around SemVer; It was only after carefully reading many other issues and discussion that I decided that the tracker might be the right place for my own suggestion.)

In short, we are all guests here.

@AloisMahdal commented on GitHub (Nov 28, 2017): @jwdonahue welcome to GitHub. Good spirit is welcome, but please note that this is a very diverse communty with very diverse practices; basically each project can have its own rules. So don't fall into the illusion that the only reason for an issue being open (and inactive) is because people forgot about it. It's perfectly OK for an issue to be open for years; not all issues represent a technical debt. Generally, people will be happy if you want to contribute to their project but they will want you to get familiar with contributing guidelines first. (If an issue is affecting you, though, it's OK to just politely ask about the state :-)). (Note: I'm not even representing community around SemVer; It was only after carefully reading many other issues and discussion that I decided that the tracker might be the right place for my own suggestion.) In short, we are all guests here.

GiteaMirror commented

2026-04-16 10:23:47 -05:00

@jwdonahue commented on GitHub (Nov 29, 2017):

@AloisMahdal, I've started another issue to discuss this, rather than further pollute your topic.

@jwdonahue commented on GitHub (Nov 29, 2017): @AloisMahdal, I've [started another issue to discuss this](https://github.com/semver/semver/issues/413), rather than further pollute your topic.

GiteaMirror commented

2026-04-16 10:23:47 -05:00

@alexandrtovmach commented on GitHub (Jun 10, 2020):

Closed as resolved, thanks everyone for contribution 👍
@AloisMahdal If you still have any questions, feel free to re-open

@alexandrtovmach commented on GitHub (Jun 10, 2020): Closed as resolved, thanks everyone for contribution :+1: @AloisMahdal If you still have any questions, feel free to re-open

GiteaMirror commented

2026-04-16 10:23:48 -05:00

@AloisMahdal commented on GitHub (Jun 11, 2020):

FTR, I have to admit that over past years I wrote dozens of CLI's but I haven't implemented this convention anywhere. I always used -V for -- just (parseable) SemVer, and --version for perhaps something more chatty.

I think the best argument against my past self would be: if --version-semver only works if consumer knows it exists (and what it means). Ie. there has to be pre-existing contract about CLI. If one wants to have such contract then it could be --version or -V right away, coupled with expectation that it has to be SemVer data.

The use case I had in mind when proposing this could still arguably make use of it: I was imagining a framework that would wrap CLI's in other interfaces, so for reporting version there would have to be such interface. (And --version could be already "occupied" by a "chatty version", and -V is too short.)

I think the reason I've never used this is that for all practical purposes it works way better to communicate version info using proper config management or package management, such as rpm, dpkg, etc. If only because it works regardless of CLI. IOW, it's unlikely that such framework would exist without relying on proper management like that so using CLI for that would be duplication.

(OTOH, that's also why I never used module.VERSION convention in Python, and yet I think their packaging still supports it.)

@AloisMahdal commented on GitHub (Jun 11, 2020): FTR, I have to admit that over past years I wrote dozens of CLI's but I haven't implemented this convention anywhere. I always used `-V` for -- just (parseable) SemVer, and `--version` for perhaps something more chatty. I think the best argument against my past self would be: if `--version-semver` only works if consumer knows it exists (and what it means). Ie. there has to be pre-existing contract about CLI. If one wants to have such contract then it could be `--version` or `-V` right away, coupled with expectation that it has to be SemVer data. The use case I had in mind when proposing this could still arguably make use of it: I was imagining a framework that would wrap CLI's in other interfaces, so for reporting version there would have to be such interface. (And `--version` could be already "occupied" by a "chatty version", and `-V` is too short.) I think the reason I've never used this is that for all practical purposes it works way better to communicate version info using proper config management or package management, such as rpm, dpkg, etc. If only because it works regardless of CLI. IOW, it's unlikely that such framework would exist without relying on proper management like that so using CLI for that would be duplication. (OTOH, that's also why I never used `module.VERSION` convention in Python, and yet I think their packaging still supports it.)

Sign in to join this conversation.

1 Participants

Notifications

Due Date

No due date set.

Dependencies

No dependencies set.

Reference: github-starred/semver#1135