man: git pull -r is a short for --rebase
PATCH 1/1 man: git pull -r is a short for --rebase
--- Documentation/git-pull.txt | 1 + 1 files changed, 1 insertions(+), 0 deletions(-)
Documentation/git-pull.txt +1 -0
@@ -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
Signature · 1 line
1.7.7
Quoted 9 lines · Miklos Vajna
--- Documentation/git-pull.txt | 1 + 1 files changed, 1 insertions(+), 0 deletions(-)Documentation/git-pull.txt +0
-0
Documentation/git-pull.txt include::merge-options.txt[] · line 107
Quoted 7 lines
Documentation/git-pull.txt +1
-0@@ -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.
Hi,
Quoted 5 lines · Junio C Hamano
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'.
Quoted 8 lines
And I do not think we particularly want to do
+-r:: +--r:: +--re:: +--reb:: +--reba:: +--rebas::
Quoted 4 lines
--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
Quoted 9 lines · Miklos Vajna
Quoted 5 lines · Junio C Hamano
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=trueI 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.
Quoted 4 lines
...
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.
Quoted 3 lines · Junio C Hamano
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.
From: "Junio C Hamano" <[email protected]>
Sent: Thursday, August 16, 2012 5:22 PM
Quoted 14 lines
Quoted 12 lines · Miklos Vajna
--- Documentation/git-pull.txt | 1 + 1 files changed, 1 insertions(+), 0 deletions(-)Documentation/git-pull.txt +0
-0@@ -101,6 +101,7 @@ include::merge-options.txt[] :git-pull: 1
Quoted 7 lines
Documentation/git-pull.txt include::merge-options.txt[] · line 107
Quoted 4 lines
Documentation/git-pull.txt +1
-0+-r:: --rebase:: Rebase the current branch on top of the upstream branch after fetching. If there is a remote-tracking branch corresponding toI 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.
Quoted 12 lines
-r|--r|--re|--reb|--reba|--rebas|--rebase)
rebase=trueAnd I do not think we particularly want to do
+-r:: +--r:: +--re:: +--reb:: +--reba:: +--rebas::
Quoted 5 lines
--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
Quoted 3 lines · Philip Oakley
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.
From: "Junio C Hamano" <[email protected]>
Sent: Thursday, August 16, 2012 9:23 PM
Quoted 6 lines
Quoted 3 lines · Philip Oakley
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?
Quoted 8 lines
$ git help gitcliis 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
Quoted 17 lines · Philip Oakley
From: "Junio C Hamano" <[email protected]>
Sent: Thursday, August 16, 2012 9:23 PMQuoted 6 lines
Quoted 3 lines · Philip Oakley
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?
Quoted 8 lines
$ git help gitcliis 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.
Quoted 6 lines
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
--- Documentation/gitcli.txt | 8 ++++++++ 1 file changed, 8 insertions(+)
Documentation/gitcli.txt +8 -0
@@ -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 ----------------------
Signature · 1 line
1.7.12.rc3.2.gbd120e3
Philip Oakley
Acked-byRe: Re* [PATCH] man: git pull -r is a short for --rebase
From: "Junio C Hamano" <[email protected]>
Sent: Friday, August 17, 2012 7:19 AM
Quoted 54 lines
Quoted 17 lines · Philip Oakley
From: "Junio C Hamano" <[email protected]>
Sent: Thursday, August 16, 2012 9:23 PMQuoted 6 lines
Quoted 3 lines · Philip Oakley
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?
Quoted 8 lines
$ git help gitcliis 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.
Quoted 6 lines
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 optionsSigned-off-by Junio C Hamano <[email protected]>---
Documentation/gitcli.txt| 8 ++++++++1 file changed, 8 insertions(+)Documentation/gitcli.txt +0
-0@@ -62,6 +62,14 @@ scripting git: `git log -1 HEAD` but write `git log -1 HEAD --`; the former willnot work
if you happen to have a file calledHEADin the work tree.+ * many commands allow a long option "--option" to be abbreviated
Documentation/gitcli.txt +7
-0+ 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. +
Quoted 4 lines
ENHANCED OPTION PARSER
----------------------Signature · 1 line
1.7.12.rc3.2.gbd120e3
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 <[email protected]>
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.
---Documentation/git.txt | 12 +++++++-----
1 files changed, 7 insertions(+), 5 deletions(-)
Documentation/git.txt +0 -0
@@ -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]).
Signature · 1 line
1.7.8.msysgit.0
Quoted 1 line
From
655c6e968fc4bb497e7ade90f2d879aadec795d9Mon Sep 17 00:00:00 2001
From: Philip Oakley <[email protected]>
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.
--- Documentation/git.txt | 12 +++++++----- 1 files changed, 7 insertions(+), 5 deletions(-)
Documentation/git.txt +7 -5
@@ -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]).
Signature · 1 line
1.7.8.msysgit.0
Re: Re* [PATCH] man: git pull -r is a short for --rebase
Quoted 13 lines · Philip Oakley
Documentation/git.txt +0
-5@@ -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.
Documentation/git.txt unusually rich command set that provides both high-level operations · line 34
Quoted 10 lines
Documentation/git.txt +7
-0+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.
--- Documentation/git.txt | 60 +++++++++++++++++++++++++++------------------------ 1 file changed, 32 insertions(+), 28 deletions(-)
Documentation/git.txt +32 -28
@@ -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
Signature · 1 line
1.7.12.rc3.71.ge297db8
Philip Oakley
Acked-byRe: Re* [PATCH] man: git pull -r is a short for --rebase
From: "Junio C Hamano" <[email protected]>
Sent: Friday, August 17, 2012 8:48 PM
Quoted 50 lines
Quoted 27 lines · Philip Oakley
Documentation/git.txt +0
-0@@ -22,11 +22,13 @@ unusually rich command set that provides bothhigh-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 mayDocumentation/git.txt +1
-3-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 ofcommands.
+Use "man git-commandname" for documentation of each command, or "git help".Documentation/git.txt +5
-0+ +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 commandline interface.
Quoted 3 lines
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.
Quoted 6 lines
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.
Quoted 5 lines
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.
Quoted 3 lines
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.
Quoted 104 lines
-- >8 --
Subject: [PATCH] Documentation: update the introductory sectionThe 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 <[email protected]>---
Documentation/git.txt| 60
+++++++++++++++++++++++++++------------------------1 file changed, 32 insertions(+), 28 deletions(-)Documentation/git.txt +0
-0@@ -22,18 +22,17 @@ unusually rich command set that provides bothhigh-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 mayDocumentation/git.txt +3
-4-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 analias
Documentation/git.txt +6
-4-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]Documentation/git.txt +0
-18@@ -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
------------Documentation/git.txt +0
-0@@ -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.
Documentation/git.txt +23
-0+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]. + +
Quoted 7 lines
Authors
-------
Git was started by Linus Torvalds, and is currently maintained by JunioSignature · 1 line
1.7.12.rc3.71.ge297db8
Am 16.08.2012 18:22, schrieb Junio C Hamano:
Quoted 14 lines
Quoted 12 lines · Miklos Vajna
--- Documentation/git-pull.txt | 1 + 1 files changed, 1 insertions(+), 0 deletions(-)Documentation/git-pull.txt +0
-0@@ -101,6 +101,7 @@ include::merge-options.txt[] :git-pull: 1
Quoted 7 lines
Documentation/git-pull.txt include::merge-options.txt[] · line 107
Quoted 4 lines
Documentation/git-pull.txt +1
-0+-r:: --rebase:: Rebase the current branch on top of the upstream branch after fetching. If there is a remote-tracking branch corresponding toI 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
Quoted 2 lines · Johannes Sixt
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.
Quoted 5 lines · Junio C Hamano
Quoted 2 lines · Johannes Sixt
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.
Quoted 7 lines
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.
Quoted 6 lines · Junio C Hamano
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.
Quoted 10 lines · Miklos Vajna
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.htmlSo 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 <[email protected]>
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(+)
Documentation/git-pull.txt +1 -0
@@ -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
Signature · 1 line
1.7.12.rc3.2.gbd120e3
Quoted 9 lines · Junio C Hamano
From: Miklos Vajna <[email protected]>
Date: Thu, 16 Aug 2012 11:50:18 +0200
Subject: [PATCH] man: git pull -r is a short for --rebaseLetting 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.
Quoted 5 lines · Miklos Vajna
Quoted 4 lines · Junio C Hamano
From: Miklos Vajna <[email protected]>
Date: Thu, 16 Aug 2012 11:50:18 +0200
Subject: [PATCH] man: git pull -r is a short for --rebase
Quoted 7 lines
Quoted 5 lines
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 <[email protected]>
Thanks.