Re: [PATCH] Documentation/fetch-options.txt: order options alphabetically

Junio C Hamano [off-list ref] writes:

Jari Aalto [off-list ref] writes:

quoted

Signed-off-by: Jari Aalto <redacted>
---
 Documentation/fetch-options.txt |   48 +++++++++++++++++++-------------------
 1 files changed, 24 insertions(+), 24 deletions(-)

Does this even make sense when git-pull.txt itself includes files other
than this one?  fetch-options.txt may begin with the description of -a
that is very early in the alphabetical sequence, but git-pull.txt includes
merge-options.txt before this file, whose contents would describe what
probably would come after -a (I didn't check).  Also git-pull.txt itself
has description of --rebase and --no-rebase that definitely come before -a
(I did check).

Ah, in your defense ;-) I think you looked only at git-fetch.txt without
checking where else this file is included.  Then the patch certainly is
understandable.  It would probably make git-fetch.{1,html} easier to scan,
while making things not worse for git-pull.{1,html}

Junio C Hamano [off-list ref] writes:

I think you looked only at git-fetch.txt without
checking where else this file is included.  Then the patch certainly is
understandable.  It would probably make git-fetch.{1,html} easier to scan,
while making things not worse for git-pull.{1,html}

Yes. Unfortunately there doesn't seem to be a way to arrange all nicely,
so perhaps you could accept the following patch to accompany with it. At
least there would be ordered "git-fetch" and semi ordered "git-pull".

    Subject: [PATCH] Documentation/merge-options.txt: order options in alphabetical groups

Jari

Quoting Junio C Hamano [off-list ref]

Ah, in your defense ;-) I think you looked only at git-fetch.txt without
checking where else this file is included.  Then the patch certainly is
understandable.  It would probably make git-fetch.{1,html} easier to scan,
while making things not worse for git-pull.{1,html}

Can't we introduce subsections in the OPTIONS section to 
group them together, like this (sorry, not a patch)?

OPTIONS
-------

Options related to merging  <---- added
~~~~~~~~~~~~~~~~~~~~~~~~~~  <---- added
include::merge-options.txt[]

:git-pull: 1

--rebase::
	Instead of a merge, perform a rebase after fetching.  If
	there is a remote ref for the upstream branch, and this branch
	was rebased since last fetched, the rebase uses that information
	to avoid rebasing non-local changes. To make this the default
	for branch `<name>`, set configuration `branch.<name>.rebase`
	to `true`.
+
[NOTE]
This is a potentially _dangerous_ mode of operation.
It rewrites history, which does not bode well when you
published that history already.  Do *not* use this option
unless you have read linkgit:git-rebase[1] carefully.

--no-rebase::
	Override earlier --rebase.

Options related to fetching  <---- added
~~~~~~~~~~~~~~~~~~~~~~~~~~~  <---- added
include::fetch-options.txt[]

include::pull-fetch-param.txt[]

-- 
Nanako Shiraishi
http://ivory.ap.teacup.com/nanako3/

On Thu, Oct 22, 2009 at 07:21:52PM +0900, Nanako Shiraishi wrote:

quoted

Ah, in your defense ;-) I think you looked only at git-fetch.txt without
checking where else this file is included.  Then the patch certainly is
understandable.  It would probably make git-fetch.{1,html} easier to scan,
while making things not worse for git-pull.{1,html}

Can't we introduce subsections in the OPTIONS section to 
group them together, like this (sorry, not a patch)?

Yes, that was my first thought when reading this thread, too (sorry, no
patch here, either. I need to sleep and then get on a plane).

-Peff

Signed-off-by: Jari Aalto <redacted>
---
 Documentation/git-pull.txt |    7 +++++++
 1 files changed, 7 insertions(+), 0 deletions(-)

 Nanako Shiraishi [off-list ref] writes:

 > Quoting Junio C Hamano [off-list ref]
 >
 >> Ah, in your defense ;-) I think you looked only at git-fetch.txt without
 >> checking where else this file is included.  Then the patch certainly is
 >> understandable.  It would probably make git-fetch.{1,html} easier to scan,
 >> while making things not worse for git-pull.{1,html}
 >
 > Can't we introduce subsections in the OPTIONS section to 
 > group them together, like this (sorry, not a patch)?
 >
 > OPTIONS
 > -------
 >
 > Options related to merging  <---- added
 > ~~~~~~~~~~~~~~~~~~~~~~~~~~  <---- added
 > include::merge-options.txt[]

diff --git a/Documentation/git-pull.txt b/Documentation/git-pull.txt
index 7578623..51534dd 100644
--- a/Documentation/git-pull.txt
+++ b/Documentation/git-pull.txt

@@ -26,6 +26,10 @@ Also note that options meant for 'git-pull' itself and underlying
 
 OPTIONS
 -------
+
+Options related to merging
+~~~~~~~~~~~~~~~~~~~~~~~~~~
+
 include::merge-options.txt[]
 
 :git-pull: 1

@@ -47,6 +51,9 @@ unless you have read linkgit:git-rebase[1] carefully.
 --no-rebase::
 	Override earlier --rebase.
 
+Options related to fetching
+~~~~~~~~~~~~~~~~~~~~~~~~~~~
+
 include::fetch-options.txt[]
 
 include::pull-fetch-param.txt[]

-- 
1.6.4.3