Re* [PATCH] man: git pull -r is a short for --rebase

"Philip Oakley" [off-list ref] writes:

From: "Junio C Hamano" <redacted>
Sent: Thursday, August 16, 2012 9:23 PM

quoted

"Philip Oakley" [off-list ref] writes:

quoted

I wasn't aware of the  "abbreviated options" capability. Is meant to
be in the man pages as I couldn't find it, or is it described
differently?

$ git help gitcli

is the closest that comes to mind.

If it is not reachable from "git help git", we may want to sprinkle
some more linkgit:gitfoo[$n] around the documentation sources.  I
didn't check.

I eventually found a reference in the parse-options API to the fact that
'Long options may be abbreviated, as long as the abbreviation is
unambiguous.'

It may be worth bringing some of those parse-options API basics bullets'
forward into the gitcli page, if appropriate.

OK, how about doing this?  Sort of killing two birds with one stone.

-- >8 --
Subject: [PATCH] gitcli: describe abbreviation of long options

Signed-off-by: Junio C Hamano <redacted>
---
 Documentation/gitcli.txt | 8 ++++++++
 1 file changed, 8 insertions(+)

diff --git a/Documentation/gitcli.txt b/Documentation/gitcli.txt
index ea17f7a..3e72a5d 100644
--- a/Documentation/gitcli.txt
+++ b/Documentation/gitcli.txt

@@ -62,6 +62,14 @@ scripting git:
    `git log -1 HEAD` but write `git log -1 HEAD --`; the former will not work
    if you happen to have a file called `HEAD` in the work tree.
 
+ * many commands allow a long option "--option" to be abbreviated
+   only to their unique prefix (e.g. if there is no other option
+   whose name begins with "opt", you may be able to spell "--opt" to
+   invoke the "--option" flag), but you should fully spell them out
+   when writing your scripts; later versions of Git may introduce a
+   new option whose name shares the same prefix, e.g. "--optimize",
+   to make a short prefix that used to be unique no longer unique.
+
 
 ENHANCED OPTION PARSER
 ----------------------

-- 
1.7.12.rc3.2.gbd120e3

From: "Junio C Hamano" <redacted>
Sent: Friday, August 17, 2012 7:19 AM

Acked-by: Philip Oakley philipoakley@iee.org

 I'd also suggest a patch to the 'git' page to bring out the command 
line interface man page, including an emphasis on each of the other 
information pages, along the lines of (probably managled/see attached):

 -- >8 --
From 655c6e968fc4bb497e7ade90f2d879aadec795d9 Mon Sep 17 00:00:00 2001
From: Philip Oakley <redacted>
Date: Fri, 17 Aug 2012 17:53:48 +0100
Subject: Include 'see gitcli' link, and separate the other links

Provide a link to the git command line interface information,
and separate for readability, the differing Tutorial, User-manual,
and CVS instruction links.

Signed-off-by: Philip Oakley <redacted>
---
 Documentation/git.txt |   12 +++++++-----
 1 files changed, 7 insertions(+), 5 deletions(-)

diff --git a/Documentation/git.txt b/Documentation/git.txt
index ca85d1d..75b35ce 100644
--- a/Documentation/git.txt
+++ b/Documentation/git.txt

@@ -22,11 +22,13 @@ unusually rich command set that provides both 

high-level operations
 and full access to internals.

 See linkgit:gittutorial[7] to get started, then see
-link:everyday.html[Everyday Git] for a useful minimum set of commands, 
and
-"man git-commandname" for documentation of each command.  CVS users may
-also want to read linkgit:gitcvs-migration[7].  See
-the link:user-manual.html[Git User's Manual] for a more in-depth
-introduction.
+link:everyday.html[Everyday Git] for a useful minimum set of commands.
+Use "man git-commandname" for documentation of each command, or "git 
help".
+
+CVS users may also want to read linkgit:gitcvs-migration[7].
+
+See the link:user-manual.html[Git User's Manual] for a more in-depth
+introduction, and linkgit:gitcli[7] for details of git's command line 
interface.

 The '<command>' is either a name of a Git command (see below) or an 
alias
 as defined in the configuration file (see linkgit:git-config[1]).
-- 
1.7.8.msysgit.0