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

From

Philip Oakley <philipoakley@iee.org>

Date

Aug 17, 2012, 18:22 UTC

Message-ID

<4E6C3BEFBD5345CC9FE0DC3C3AD41788@PhilipOakley>

In-Reply-To

<7vfw7mvy40.fsf_-_@alter.siamese.dyndns.org>

From: "Junio C Hamano" <gitster@pobox.com>
Sent: Friday, August 17, 2012 7:19 AM

> "Philip Oakley" <philipoakley@iee.org> writes:
>
>> From: "Junio C Hamano" <gitster@pobox.com>
>> Sent: Thursday, August 16, 2012 9:23 PM
>>> "Philip Oakley" <philipoakley@iee.org> writes:
>>>
>>>> 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 <gitster@pobox.com>
> ---
> 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

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 <philipoakley@iee.org>
Date: Fri, 17 Aug 2012 17:53:48 +0100
Subject: Include 'see gitcli' link, and separate the other links

Signed-off-by: Philip Oakley <philipoakley@iee.org>
---
 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





>From 655c6e968fc4bb497e7ade90f2d879aadec795d9 Mon Sep 17 00:00:00 2001
From: Philip Oakley <philipoakley@iee.org>
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 <philipoakley@iee.org>
---
 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