Re: Re* [PATCH] man: git pull -r is a short for --rebase
From: Junio C Hamano gits...@pobox.com Sent: Friday, August 17, 2012 7:19 AM Philip Oakley philipoak...@iee.org writes: From: Junio C Hamano gits...@pobox.com Sent: Thursday, August 16, 2012 9:23 PM Philip Oakley philipoak...@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 gits...@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 philipoak...@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 philipoak...@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 philipoak...@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 0001-Include-see-gitcli-link-and-separate-the-other-links.patch Description: Binary data
Re: Re* [PATCH] man: git pull -r is a short for --rebase
Philip Oakley philipoak...@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 gits...@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
Re: Re* [PATCH] man: git pull -r is a short for --rebase
From: Junio C Hamano gits...@pobox.com Sent: Friday, August 17, 2012 8:48 PM Philip Oakley philipoak...@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 gits...@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
