patchhelp.c: add a compatibility comment to cmd_version()

> External projects have been known to parse the output of
> "git version".  Help prevent future authors from changing
> its format by adding a comment to its implementation.
>
> Signed-off-by: David Aguilar <davvid@gmail.com>
> ---
>  help.c | 4 ++++
>  1 file changed, 4 insertions(+)
>
> diff --git a/help.c b/help.c
> index 1dfa0b0..02ba043 100644
> --- a/help.c
> +++ b/help.c
> @@ -397,6 +397,10 @@ const char *help_unknown_cmd(const char *cmd)
>  
>  int cmd_version(int argc, const char **argv, const char *prefix)
>  {
> +	/*
> +	 * The format of this string should be kept stable for compatibility
> +	 * with external projects that rely on the output of "git version".
> +	 */
>  	printf("git version %s\n", git_version_string);
>  	return 0;
>  }

> External projects have been known to parse the output of
> "git version".  Help prevent future authors from changing
> its format by adding a comment to its implementation.
>
> Signed-off-by: David Aguilar <davvid@gmail.com>
> ---
> help.c | 4 ++++
> 1 file changed, 4 insertions(+)
>
> diff --git a/help.c b/help.c
> index 1dfa0b0..02ba043 100644
> --- a/help.c
> +++ b/help.c
> @@ -397,6 +397,10 @@ const char *help_unknown_cmd(const char *cmd)
>
> int cmd_version(int argc, const char **argv, const char *prefix)
> {
> + /*
> + * The format of this string should be kept stable for compatibility
> + * with external projects that rely on the output of "git version".

> + */
>  printf("git version %s\n", git_version_string);
>  return 0;
> }
> -- 
> 1.8.2.1.652.ge104b5e
>
> --
> To unsubscribe from this list: send the line "unsubscribe git" in
> the body of a message to majordomo@vger.kernel.org
> More majordomo info at  http://vger.kernel.org/majordomo-info.html
>
>
> -----
> No virus found in this message.
> Checked by AVG - www.avg.com
> Version: 2013.0.3272 / Virus Database: 3162/6248 - Release Date: 
> 04/16/13
> 

>> int cmd_version(int argc, const char **argv, const char *prefix)
>> {
>> + /*
>> + * The format of this string should be kept stable for compatibility
>> + * with external projects that rely on the output of "git version".
>
> Shouldn't the expected format of our known external project also be
> indicated?
> ...
>>  printf("git version %s\n", git_version_string);

> "Philip Oakley" <philipoakley@iee.org> writes:
>
>>> int cmd_version(int argc, const char **argv, const char *prefix)
>>> {
>>> + /*
>>> + * The format of this string should be kept stable for 
>>> compatibility
>>> + * with external projects that rely on the output of "git version".

>>
>> Shouldn't the expected format of our known external project also be
>> indicated?
>> ...
>>>  printf("git version %s\n", git_version_string);
>
> It is fairly clear from the commented code that the only guarantee
> they will be getting is that it begins with a string "git version ".

> git_version_string[] has anything of the builder's choice.  I am not
> sure if there anything more to "indicate".
>
> Really, if you run
>
> $ git version
>
> and you get "Git Source Code Management Version 3.56" from its
> output, it is likely that the version is very different from what
> you know, and you should not assume any your assumption would hold.

>
>> Or mention "such as git gui"?
>
> I do not see what it would buy us.  It is not like it is OK as long
> as we upadte Git gui at the same time.

> How about
>    * E.g. git gui uses the extended regular expression "^git version
> [1-9]+(\.[0-9]+)+.*"
>    * to check for an acceptable version string.
>
> The ERE is from git-gui.sh:L958.

> "Philip Oakley" <philipoakley@iee.org> writes:
>
>> How about
>>    * E.g. git gui uses the extended regular expression "^git version
>> [1-9]+(\.[0-9]+)+.*"
>>    * to check for an acceptable version string.
>>
>> The ERE is from git-gui.sh:L958.
>
> That is exactly the kind of guarantee we do _not_ want to give.
>

>> ... Hence my suggestion of the basic test that a "passing" git
>> would produce a consistent version string.
>
> I have been assuming that you are trying to avoid an exchange like
> this one we had in the past:
>
> 
> http://thread.gmane.org/gmane.comp.version-control.git/216923/focus=217007
>

> I also have been assuming that you are pushing to limit the possible
> versioning scheme, but I do not know what that extra limitation
> would achieve in the real world.
>
> By sticking to the pattern "git gui" happens to use, "git gui" may
> be able to guess that the next version of Git says it is verison
> "1.8.3".  That is the _only_ thing your "test" buys.
>
> But having parsed the "1.8.3" substring out of it, "git gui" does
> not know anything about what 1.8.3 gives it.  As far as it is
> concerned, it is a version whose "git version" output it has never
> seen (unless it has been kept up to date with the development of
> Git).

>
> By matching against "git version [1-9]+(\.[0-9]+)+", it is accepting
> that future versions may break assumptions it makes for some known
> versions (which is warranted) and all future versions (which is
> unwarranted) of Git.  Maybe the version 2.0 of Git adds all changes
> in the directory "d", including removals, when you say "git add d",
> but it may have assumed that with Git version 1.5.0 or newer, saying
> "git add d" would result in added and modified inside that directory
> getting updated in the index, but paths removed from the working
> tree will stay in the index.

>
> The only thing the scripts that read from the output of "git
> version" can reliably tell is if it is interacting with a version of
> Git it knows about.  If it made any unwarranted assumption on the
> versions it hasn't seen, it has to be fixed in "git gui" _anyway_.
>
> Of course, we would not change the output of "git version"
> willy-nilly without good reason, but that is a different topic.

>
> So I do not know what you want to achieve in the real world with
> that extra limitation on the "git version" output format.
>
> Maybe you are proposing something else.  I dunno.