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

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

[Jari Aalto]

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

diff --git a/Documentation/fetch-options.txt b/Documentation/fetch-options.txt
index 5eb2b0e..2886874 100644
--- a/Documentation/fetch-options.txt
+++ b/Documentation/fetch-options.txt
@@ -1,25 +1,13 @@
-ifndef::git-pull[]
--q::
---quiet::
-	Pass --quiet to git-fetch-pack and silence any other internally
-	used git commands.
-
--v::
---verbose::
-	Be verbose.
-endif::git-pull[]
-
 -a::
 --append::
 	Append ref names and object names of fetched refs to the
 	existing contents of `.git/FETCH_HEAD`.  Without this
 	option old data in `.git/FETCH_HEAD` will be overwritten.
 
---upload-pack <upload-pack>::
-	When given, and the repository to fetch from is handled
-	by 'git-fetch-pack', '--exec=<upload-pack>' is passed to
-	the command to specify non-default path for the command
-	run on the other end.
+--depth=<depth>::
+	Deepen the history of a 'shallow' repository created by
+	`git clone` with `--depth=<depth>` option (see linkgit:git-clone[1])
+	by the specified number of commits.
 
 -f::
 --force::
@@ -29,6 +17,10 @@ endif::git-pull[]
 	fetches is a descendant of `<lbranch>`.  This option
 	overrides that check.
 
+-k::
+--keep::
+	Keep downloaded pack.
+
 ifdef::git-pull[]
 --no-tags::
 endif::git-pull[]
@@ -49,10 +41,6 @@ endif::git-pull[]
 	flag lets all tags and their associated objects be
 	downloaded.
 
--k::
---keep::
-	Keep downloaded pack.
-
 -u::
 --update-head-ok::
 	By default 'git-fetch' refuses to update the head which
@@ -62,7 +50,19 @@ endif::git-pull[]
 	implementing your own Porcelain you are not supposed to
 	use it.
 
---depth=<depth>::
-	Deepen the history of a 'shallow' repository created by
-	`git clone` with `--depth=<depth>` option (see linkgit:git-clone[1])
-	by the specified number of commits.
+--upload-pack <upload-pack>::
+	When given, and the repository to fetch from is handled
+	by 'git-fetch-pack', '--exec=<upload-pack>' is passed to
+	the command to specify non-default path for the command
+	run on the other end.
+
+ifndef::git-pull[]
+-q::
+--quiet::
+	Pass --quiet to git-fetch-pack and silence any other internally
+	used git commands.
+
+-v::
+--verbose::
+	Be verbose.
+endif::git-pull[]
-- 
1.6.4.3

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

[Junio C Hamano]

Jari Aalto <jari.aalto@cante.net> writes:

> Signed-off-by: Jari Aalto <jari.aalto@cante.net>
> ---
>  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).

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

[Junio C Hamano]

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

> Jari Aalto <jari.aalto@cante.net> writes:
>
>> Signed-off-by: Jari Aalto <jari.aalto@cante.net>
>> ---
>>  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}

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

[Jari Aalto]

Junio C Hamano <gitster@pobox.com> 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

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

[Nanako Shiraishi]

Quoting Junio C Hamano <gitster@pobox.com>

> 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/

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

[Jeff King]

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

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

[PATCH] Documentation/git-pull.txt: Add subtitles above included option files

[Jari Aalto]

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

 Nanako Shiraishi <nanako3@lavabit.com> writes:

 > Quoting Junio C Hamano <gitster@pobox.com>
 >
 >> 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