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

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

[Miklos Vajna]

---
 Documentation/git-pull.txt |    1 +
 1 files changed, 1 insertions(+), 0 deletions(-)

diff --git a/Documentation/git-pull.txt b/Documentation/git-pull.txt
index defb544..67fa5ee 100644
--- a/Documentation/git-pull.txt
+++ b/Documentation/git-pull.txt
@@ -101,6 +101,7 @@ include::merge-options.txt[]
 
 :git-pull: 1
 
+-r::
 --rebase::
 	Rebase the current branch on top of the upstream branch after
 	fetching.  If there is a remote-tracking branch corresponding to
-- 
1.7.7

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

[Junio C Hamano]

Miklos Vajna <vmiklos@suse.cz> writes:

> ---
>  Documentation/git-pull.txt |    1 +
>  1 files changed, 1 insertions(+), 0 deletions(-)
>
> diff --git a/Documentation/git-pull.txt b/Documentation/git-pull.txt
> index defb544..67fa5ee 100644
> --- a/Documentation/git-pull.txt
> +++ b/Documentation/git-pull.txt
> @@ -101,6 +101,7 @@ include::merge-options.txt[]
>  
>  :git-pull: 1
>  
> +-r::
>  --rebase::
>  	Rebase the current branch on top of the upstream branch after
>  	fetching.  If there is a remote-tracking branch corresponding to

I am not sure if this is worth it, as it comes from a natural
"abbreviated options" support, i.e.

	-r|--r|--re|--reb|--reba|--rebas|--rebase)
		rebase=true

And I do not think we particularly want to do

    +-r::
    +--r::
    +--re::
    +--reb::
    +--reba::
    +--rebas::
     --rebase::
            Rebase the current...

for obvious reasons.

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

[Miklos Vajna]

Hi,

On Thu, Aug 16, 2012 at 09:22:14AM -0700, Junio C Hamano <gitster@pobox.com> wrote:
> I am not sure if this is worth it, as it comes from a natural
> "abbreviated options" support, i.e.
> 
> 	-r|--r|--re|--reb|--reba|--rebas|--rebase)
> 		rebase=true

I sent the patch as a (newcomer) friend today asked if it's intentional
that -r is undocumented in 'man git-pull'.

> And I do not think we particularly want to do
> 
>     +-r::
>     +--r::
>     +--re::
>     +--reb::
>     +--reba::
>     +--rebas::
>      --rebase::
>             Rebase the current...
> 
> for obvious reasons.

I agree, however, we already document -q and --quiet, or -v and
--verbose in the same manpage, so I think it would be consistent to have
-r there as well.

Thanks,

Miklos

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

[Philip Oakley]

From: "Junio C Hamano" <gitster@pobox.com>
Sent: Thursday, August 16, 2012 5:22 PM
> Miklos Vajna <vmiklos@suse.cz> writes:
>
>> ---
>>  Documentation/git-pull.txt |    1 +
>>  1 files changed, 1 insertions(+), 0 deletions(-)
>>
>> diff --git a/Documentation/git-pull.txt b/Documentation/git-pull.txt
>> index defb544..67fa5ee 100644
>> --- a/Documentation/git-pull.txt
>> +++ b/Documentation/git-pull.txt
>> @@ -101,6 +101,7 @@ include::merge-options.txt[]
>>
>>  :git-pull: 1
>>
>> +-r::
>>  --rebase::
>>  Rebase the current branch on top of the upstream branch after
>>  fetching.  If there is a remote-tracking branch corresponding to
>
> I am not sure if this is worth it, as it comes from a natural
> "abbreviated options" support, i.e.

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?

Just adding the '-r' part of the option did seem sensible to me as a 
relative newbie.

>
> -r|--r|--re|--reb|--reba|--rebas|--rebase)
> rebase=true
>
> And I do not think we particularly want to do
>
>    +-r::
>    +--r::
>    +--re::
>    +--reb::
>    +--reba::
>    +--rebas::
>     --rebase::
>            Rebase the current...
>
> for obvious reasons.
> --

The extra one liner (-r|--r|--re|--reb|--reba|--rebas)  would be 
readable though not pretty, but the seven line version would be 
horrible!

Philip 

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

[Junio C Hamano]

Miklos Vajna <vmiklos@suse.cz> writes:

> On Thu, Aug 16, 2012 at 09:22:14AM -0700, Junio C Hamano <gitster@pobox.com> wrote:
>> I am not sure if this is worth it, as it comes from a natural
>> "abbreviated options" support, i.e.
>> 
>> 	-r|--r|--re|--reb|--reba|--rebas|--rebase)
>> 		rebase=true
>
> I sent the patch as a (newcomer) friend today asked if it's intentional
> that -r is undocumented in 'man git-pull'.

It is more intentional than it is by accident that we don't.

We would really think hard to avoid breaking when introducing new
options whose long name could begin with "v" or "q" to avoid
breaking "-v" and "-q" that are common across commands, but it is
entirely plausible that we want to add a new option whose name
begins with "re", and at that point, "-r" or "--re" stop being the
unique short form to trigger "git pull --rebase".

If somebody figures out "git pull --reba" or even "git pull -r"
works by accident _today_ and gets used to using it, that is fine,
but we do not want to guarantee the future.  We reserve the right to
introduce "git pull --repurpose" in a later version of Git, and make
"git pull --re" error out for ambiguity, breaking fingers of such
people who relied on "used to be but no longer" unique
abbreviations.

> ...
> I agree, however, we already document -q and --quiet, or -v and
> --verbose in the same manpage, so I think it would be consistent to have
> -r there as well.

See above.

Thanks.

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

[Junio C Hamano]

"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.

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

[Junio C Hamano]

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

> We would really think hard to avoid breaking when introducing new
> options whose long name could begin with "v" or "q" to avoid
> breaking "-v" and "-q" that are common across commands

[today's lesson for me; do not type while eating]

Sorry.

        We would really think hard to avoid breaking "-v" and "-q"
        that are common across commands, when introducing new
        options whose long names could begin with "v" or "q".

I tried to rephrase/reorganize the sentence a few times by moving
words around, but did a terrible job at it.

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

[Johannes Sixt]

Am 16.08.2012 18:22, schrieb Junio C Hamano:
> Miklos Vajna <vmiklos@suse.cz> writes:
> 
>> ---
>>  Documentation/git-pull.txt |    1 +
>>  1 files changed, 1 insertions(+), 0 deletions(-)
>>
>> diff --git a/Documentation/git-pull.txt b/Documentation/git-pull.txt
>> index defb544..67fa5ee 100644
>> --- a/Documentation/git-pull.txt
>> +++ b/Documentation/git-pull.txt
>> @@ -101,6 +101,7 @@ include::merge-options.txt[]
>>  
>>  :git-pull: 1
>>  
>> +-r::
>>  --rebase::
>>  	Rebase the current branch on top of the upstream branch after
>>  	fetching.  If there is a remote-tracking branch corresponding to
> 
> I am not sure if this is worth it, as it comes from a natural
> "abbreviated options" support,

Are you sure? This adds '-r', not '--r', i.e., the single-letter option
'r', to the documentation, which is not something we want to hide, usually.

-- Hannes

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

[Junio C Hamano]

Johannes Sixt <j6t@kdbg.org> writes:

> Are you sure? This adds '-r', not '--r', i.e., the single-letter option
> 'r', to the documentation, which is not something we want to hide, usually.

I actually think "--rebase" squatting on short-and-sweet "-r" was an
accident, and we are saved by not endorsing "pull -r" by documenting
it.  We can still use "-r" for "--recurse-submodules" if that proves
to give more value than "--rebase" to our users.

So I dunno.  I personally do not think either deserves a short-and-sweet
single letter option.

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

[Junio C Hamano]

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

> Johannes Sixt <j6t@kdbg.org> writes:
>
>> Are you sure? This adds '-r', not '--r', i.e., the single-letter option
>> 'r', to the documentation, which is not something we want to hide, usually.
>
> I actually think "--rebase" squatting on short-and-sweet "-r" was an
> accident, and we are saved by not endorsing "pull -r" by documenting
> it.  We can still use "-r" for "--recurse-submodules" if that proves
> to give more value than "--rebase" to our users.
>
> So I dunno.  I personally do not think either deserves a short-and-sweet
> single letter option.

I guess the above needs a bit of clarification.

The reason I do not think "pull -r" gives much value to the users to
trigger "pull --rebase" is because the use of "pull --rebase" is
very project specific.  If you are working on a project that forbids
merges, you would _always_ want to run "pull --rebase", which means
you would likely have it configured and would not be typing from the
command line.

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

[Philip Oakley]

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.

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

[Miklos Vajna]

On Thu, Aug 16, 2012 at 02:09:33PM -0700, Junio C Hamano <gitster@pobox.com> wrote:
> The reason I do not think "pull -r" gives much value to the users to
> trigger "pull --rebase" is because the use of "pull --rebase" is
> very project specific.  If you are working on a project that forbids
> merges, you would _always_ want to run "pull --rebase", which means
> you would likely have it configured and would not be typing from the
> command line.

I agree that it's a bit strange, but based on a quick search, it seems
multiple projects already advertise git pull -r (i.e. not --rebase and
not a configuration option):

http://lilypond.org/doc/v2.15/Documentation/contributor/pulling-and-rebasing
http://wiki.documentfoundation.org/Git_For_LibreOffice_Developers
http://www.wiremod.com/forum/wiremod-general-chat/29517-git-introduction-incomplete-unformatted.html

So it seems making -r refer to --recurse-submodules would already cause
quite some pain to users.

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

[Junio C Hamano]

Miklos Vajna <vmiklos@suse.cz> writes:

> I agree that it's a bit strange, but based on a quick search, it seems
> multiple projects already advertise git pull -r (i.e. not --rebase and
> not a configuration option):
>
> http://lilypond.org/doc/v2.15/Documentation/contributor/pulling-and-rebasing
> http://wiki.documentfoundation.org/Git_For_LibreOffice_Developers
> http://www.wiremod.com/forum/wiremod-general-chat/29517-git-introduction-incomplete-unformatted.html
>
> So it seems making -r refer to --recurse-submodules would already cause
> quite some pain to users.

Yuck. I could say it's not our problem that others spread something
we didn't document ;-) but I am too nice to say that.

Let's do this, then, but you have to sign off your patch.

Thanks for investigating.

-- >8 --
From: Miklos Vajna <vmiklos@suse.cz>
Date: Thu, 16 Aug 2012 11:50:18 +0200
Subject: [PATCH] man: git pull -r is a short for --rebase

Letting the "--rebase" option squat on the short-and-sweet single
letter option "-r" was an unintended accident and was not even
documented, but the short option seems to be already used in the
wild. Let's document it so that other options that begin with "r"
would not be tempted to steal it.
---
 Documentation/git-pull.txt | 1 +
 1 file changed, 1 insertion(+)

diff --git a/Documentation/git-pull.txt b/Documentation/git-pull.txt
index defb544..67fa5ee 100644
--- a/Documentation/git-pull.txt
+++ b/Documentation/git-pull.txt
@@ -101,6 +101,7 @@ include::merge-options.txt[]
 
 :git-pull: 1
 
+-r::
 --rebase::
 	Rebase the current branch on top of the upstream branch after
 	fetching.  If there is a remote-tracking branch corresponding to
-- 
1.7.12.rc3.2.gbd120e3

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

[Junio C Hamano]

"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

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

[Miklos Vajna]

On Thu, Aug 16, 2012 at 11:18:40PM -0700, Junio C Hamano <gitster@pobox.com> wrote:
> From: Miklos Vajna <vmiklos@suse.cz>
> Date: Thu, 16 Aug 2012 11:50:18 +0200
> Subject: [PATCH] man: git pull -r is a short for --rebase
> 
> Letting the "--rebase" option squat on the short-and-sweet single
> letter option "-r" was an unintended accident and was not even
> documented, but the short option seems to be already used in the
> wild. Let's document it so that other options that begin with "r"
> would not be tempted to steal it.

Signed-off-by: Miklos Vajna <vmiklos@suse.cz>

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

[Junio C Hamano]

Miklos Vajna <vmiklos@suse.cz> writes:

> On Thu, Aug 16, 2012 at 11:18:40PM -0700, Junio C Hamano <gitster@pobox.com> wrote:
>> From: Miklos Vajna <vmiklos@suse.cz>
>> Date: Thu, 16 Aug 2012 11:50:18 +0200
>> Subject: [PATCH] man: git pull -r is a short for --rebase
>> 
>> Letting the "--rebase" option squat on the short-and-sweet single
>> letter option "-r" was an unintended accident and was not even
>> documented, but the short option seems to be already used in the
>> wild. Let's document it so that other options that begin with "r"
>> would not be tempted to steal it.
>
> Signed-off-by: Miklos Vajna <vmiklos@suse.cz>

Thanks.

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

[Philip Oakley]

[-- Attachment #1: Type: text/plain, Size: 4128 bytes --]

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

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




[-- Attachment #2: 0001-Include-see-gitcli-link-and-separate-the-other-links.patch --]
[-- Type: application/octet-stream, Size: 1700 bytes --]

>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

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

[Junio C Hamano]

"Philip Oakley" <philipoakley@iee.org> writes:

> 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]).

I would prefer to keep the description section of git(1) not overly
long.

The first paragraph (not much shown above) concisely describes what
Git is, so that people who were interested in other "git" can
quickly tell that this is not a page to read about it.  I think it
is in good shape.

The purpose of the second paragraph is to guide people who are not
ready to dive into this page and refer them to other pages with the
introductory material, and also tell them that they can come back to
this page to learn the set of commands Git offers once they are
familiar with the concepts.

And then, before going into the list of commands, we should tell
them what we are listing, and where they can find more information.

So in that sense, we would really want to keep the second paragraph
short and to the point.  Referring migrating CVS users to another
page before they get acquainted with Git like the current page does
is a mistake.  On the other hand, gitcli may deserve to be mentioned
in the third paragraph that gives the reader the sense of the overall
structure of the documentation.

The mention of cvs migration used to be more important in earlier
days, but I think it was out of place to have it early in the
document even back then.  It probably can be moved down to the
FURTHER DOCUMENTATION section.

So how about doing it this way?

-- >8 --
Subject: [PATCH] Documentation: update the introductory section

The second paragraph in the git(1) description section were meant to
guide people who are not ready to dive into this page away from here.
Referring migrating CVS users to another page before they get
acquainted with Git was somewhat out of place.  Move the reference to
the "FURTHER DOCUMENTATION" section and push that section down.

Signed-off-by: Junio C Hamano <gitster@pobox.com>
---
 Documentation/git.txt | 60 +++++++++++++++++++++++++++------------------------
 1 file changed, 32 insertions(+), 28 deletions(-)

diff --git a/Documentation/git.txt b/Documentation/git.txt
index eb6b2c0..33028a9 100644
--- a/Documentation/git.txt
+++ b/Documentation/git.txt
@@ -22,18 +22,17 @@ 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.  The link:user-manual.html[Git User's Manual] has a more
+in-depth introduction.
 
-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]).
+After you mastered the basic concepts, you can come back to this
+page to learn what commands git offers.  You can learn more about
+individual git commands with "git help command".  linkgit:gitcli[7]
+manual page gives you an overview of the command line command syntax.
 
-Formatted and hyperlinked version of the latest git
-documentation can be viewed at
-`http://git-htmldocs.googlecode.com/git/git.html`.
+Formatted and hyperlinked version of the latest git documentation
+can be viewed at `http://git-htmldocs.googlecode.com/git/git.html`.
 
 ifdef::stalenotes[]
 [NOTE]
@@ -406,24 +405,6 @@ help ...`.
 	linkgit:git-replace[1] for more information.
 
 
-FURTHER DOCUMENTATION
----------------------
-
-See the references above to get started using git.  The following is
-probably more detail than necessary for a first-time user.
-
-The link:user-manual.html#git-concepts[git concepts chapter of the
-user-manual] and linkgit:gitcore-tutorial[7] both provide
-introductions to the underlying git architecture.
-
-See linkgit:gitworkflows[7] for an overview of recommended workflows.
-
-See also the link:howto-index.html[howto] documents for some useful
-examples.
-
-The internals are documented in the
-link:technical/api-index.html[GIT API documentation].
-
 GIT COMMANDS
 ------------
 
@@ -843,6 +824,29 @@ The index is also capable of storing multiple entries (called "stages")
 for a given pathname.  These stages are used to hold the various
 unmerged version of a file when a merge is in progress.
 
+FURTHER DOCUMENTATION
+---------------------
+
+See the references in the "description" section to get started
+using git.  The following is probably more detail than necessary
+for a first-time user.
+
+The link:user-manual.html#git-concepts[git concepts chapter of the
+user-manual] and linkgit:gitcore-tutorial[7] both provide
+introductions to the underlying git architecture.
+
+See linkgit:gitworkflows[7] for an overview of recommended workflows.
+
+See also the link:howto-index.html[howto] documents for some useful
+examples.
+
+The internals are documented in the
+link:technical/api-index.html[GIT API documentation].
+
+Users migrating from CVS may also want to
+read linkgit:gitcvs-migration[7].
+
+
 Authors
 -------
 Git was started by Linus Torvalds, and is currently maintained by Junio
-- 
1.7.12.rc3.71.ge297db8

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

[Philip Oakley]

From: "Junio C Hamano" <gitster@pobox.com>
Sent: Friday, August 17, 2012 8:48 PM
> "Philip Oakley" <philipoakley@iee.org> writes:
>
>> 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]).
>
> I would prefer to keep the description section of git(1) not overly
> long.
>
> The first paragraph (not much shown above) concisely describes what
> Git is, so that people who were interested in other "git" can
> quickly tell that this is not a page to read about it.  I think it
> is in good shape.
>
> The purpose of the second paragraph is to guide people who are not
> ready to dive into this page and refer them to other pages with the
> introductory material, and also tell them that they can come back to
> this page to learn the set of commands Git offers once they are
> familiar with the concepts.
>
> And then, before going into the list of commands, we should tell
> them what we are listing, and where they can find more information.
>
> So in that sense, we would really want to keep the second paragraph
> short and to the point.  Referring migrating CVS users to another
> page before they get acquainted with Git like the current page does
> is a mistake.  On the other hand, gitcli may deserve to be mentioned
> in the third paragraph that gives the reader the sense of the overall
> structure of the documentation.

Certainly for those learning and in need of help, keeping paragraphs
short, to the point, and easy to read is a definate advantage. Once they
have found the right command then the documentation can become terse man
pages providing precise details. Your arrangement makes sense.

>
> The mention of cvs migration used to be more important in earlier
> days, but I think it was out of place to have it early in the
> document even back then.  It probably can be moved down to the
> FURTHER DOCUMENTATION section.

True.

At some point (in the future) the method of accessing the 
guides/articles (rather than the commands) should be mentioned 
(somewhere). e.g. that gittutorial can be accessed via 'git 
tutorial --help' or 'git help tutorial', along with 'git k' etc.
>
> So how about doing it this way?
>
I'm on msysgit so don't have the ascii docs tool chain, so I'm 
visualising.  Ack.
> -- >8 --
> Subject: [PATCH] Documentation: update the introductory section
>
> The second paragraph in the git(1) description section were meant to
> guide people who are not ready to dive into this page away from here.
> Referring migrating CVS users to another page before they get
> acquainted with Git was somewhat out of place.  Move the reference to
> the "FURTHER DOCUMENTATION" section and push that section down.
>
> Signed-off-by: Junio C Hamano <gitster@pobox.com>
> ---
> Documentation/git.txt | 60
> +++++++++++++++++++++++++++------------------------
> 1 file changed, 32 insertions(+), 28 deletions(-)
>
> diff --git a/Documentation/git.txt b/Documentation/git.txt
> index eb6b2c0..33028a9 100644
> --- a/Documentation/git.txt
> +++ b/Documentation/git.txt
> @@ -22,18 +22,17 @@ 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.  The link:user-manual.html[Git User's Manual] has a more
> +in-depth introduction.
>
> -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]).
> +After you mastered the basic concepts, you can come back to this
> +page to learn what commands git offers.  You can learn more about
> +individual git commands with "git help command".  linkgit:gitcli[7]
> +manual page gives you an overview of the command line command syntax.
>
> -Formatted and hyperlinked version of the latest git
> -documentation can be viewed at
> -`http://git-htmldocs.googlecode.com/git/git.html`.
> +Formatted and hyperlinked version of the latest git documentation
> +can be viewed at `http://git-htmldocs.googlecode.com/git/git.html`.
>
> ifdef::stalenotes[]
> [NOTE]
> @@ -406,24 +405,6 @@ help ...`.
>  linkgit:git-replace[1] for more information.
>
>
> -FURTHER DOCUMENTATION
> ----------------------
> -
> -See the references above to get started using git.  The following is
> -probably more detail than necessary for a first-time user.
> -
> -The link:user-manual.html#git-concepts[git concepts chapter of the
> -user-manual] and linkgit:gitcore-tutorial[7] both provide
> -introductions to the underlying git architecture.
> -
> -See linkgit:gitworkflows[7] for an overview of recommended workflows.
> -
> -See also the link:howto-index.html[howto] documents for some useful
> -examples.
> -
> -The internals are documented in the
> -link:technical/api-index.html[GIT API documentation].
> -
> GIT COMMANDS
> ------------
>
> @@ -843,6 +824,29 @@ The index is also capable of storing multiple
> entries (called "stages")
> for a given pathname.  These stages are used to hold the various
> unmerged version of a file when a merge is in progress.
>
> +FURTHER DOCUMENTATION
> +---------------------
> +
> +See the references in the "description" section to get started
> +using git.  The following is probably more detail than necessary
> +for a first-time user.
> +
> +The link:user-manual.html#git-concepts[git concepts chapter of the
> +user-manual] and linkgit:gitcore-tutorial[7] both provide
> +introductions to the underlying git architecture.
> +
> +See linkgit:gitworkflows[7] for an overview of recommended workflows.
> +
> +See also the link:howto-index.html[howto] documents for some useful
> +examples.
> +
> +The internals are documented in the
> +link:technical/api-index.html[GIT API documentation].
> +
> +Users migrating from CVS may also want to
> +read linkgit:gitcvs-migration[7].
> +
> +
> Authors
> -------
> Git was started by Linus Torvalds, and is currently maintained by
> Junio
> -- 
> 1.7.12.rc3.71.ge297db8
>
Acked-by: Philip Oakley <philipoakley@iee.org>