Re: git commit --amen

[Junio C Hamano <gitster@pobox.com>]

Junio C Hamano <gitster@pobox.com> writes:

> Phil Hord <phil.hord@gmail.com> writes:
>
>>> Is it normal that "git commit --amen" actually works ?
>>> (it does like --amend)
>>>
>>> version 1.7.10.4
>>
>> Yes.  From Documentation/technical/api-parse-options.txt:
>>
>>     * Long options may be 'abbreviated', as long as the abbreviation
>>       is unambiguous.
>>
>> Apparently since 2008-06-22.
>
> Notice "technical/api-" part; that is a _wrong_ documentation page
> to quote to end users.
>
> Instead quote from "git help cli".
>
>        From the git 1.5.4 series and further, many git commands (not
>        all of them at the time of the writing though) come with an
>        enhanced option parser.
>
>> So 'git commit --am' also works.  But it should probably be avoided
>> because of its similarity to 'git commit -am'.
>
> Yes, in general, you should avoid relying on shortened form
> working.  Git 2.4 may add an option "--amen" that has totally
> different meaning.

Perhaps a patch along this line might not hurt.

 Documentation/gitcli.txt | 12 +++++++++++-
 1 file changed, 11 insertions(+), 1 deletion(-)

diff --git i/Documentation/gitcli.txt w/Documentation/gitcli.txt
index f6ba90c..3bc1500 100644
--- i/Documentation/gitcli.txt
+++ w/Documentation/gitcli.txt
@@ -93,7 +93,7 @@ ENHANCED OPTION PARSER
 From the git 1.5.4 series and further, many git commands (not all of them at the
 time of the writing though) come with an enhanced option parser.
 
-Here is an exhaustive list of the facilities provided by this option parser.
+Here is a list of the facilities provided by this option parser.
 
 
 Magic Options
@@ -137,6 +137,16 @@ options. This means that you can for example use `git rm -rf` or
 `git clean -fdx`.
 
 
+Abbreviating long options
+~~~~~~~~~~~~~~~~~~~~~~~~~
+Commands that support the enhanced option parser accepts unique
+prefix of a long option as if it is fully spelled out, but use this
+with a caution.  For example, `git commit --amen` behaves as if you
+typed `git commit --amend`, but that is true only until a later version
+of Git introduces another option that shares the same prefix,
+e.g `git commit --amenity" option.
+
+
 Separating argument from the option
 ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
 You can write the mandatory option parameter to an option as a separate