[PATCH] git-rev-list.txt: prune options in synopsis

[PATCH] git-rev-list.txt: prune options in synopsis

[Denton Liu]

The synopsis section in git-rev-list.txt has grown to be a huge list
that probably needs its own synopsis. Since the list is huge, users may
be given the false impression that the list is complete, however it is
not. It is missing many of the available options.

Since the list of options in the synopsis is not only annoying but
actively harmful, replace it with `[<options>]` so users know to
explicitly look through the documentation for further information.

While we're at it, update the optional path notation so that it is more
modern.

Signed-off-by: Denton Liu <liu.denton@gmail.com>
---
I initially wrote a patch to document --children in the synopsis
alongside --parents. However, I quickly realised that --children was
only one of many missing options. Other options included:

	--since
	--after
	--until
	--before
	--show-notes
	--all-match
	--invert-grep
	--basic-regexp
	--perl-regexp
	--exclude
	--reflog
	--alternate-refs
	--single-worktree
	--boundary
	--progress
	--simplify-by-decoration
	... stopped checking here

so I decided it wasn't worth it to keep this list around if it's so
incomplete when even the porcelain git-log.txt doesn't carry a huge list
in the synopsis.

I went through and manually checked each option to ensure that there was
a corresponding option in either rev-list-options.txt or
pretty-options.txt so we shouldn't lose any information by deleting this
list.

 Documentation/git-rev-list.txt | 54 +---------------------------------
 1 file changed, 1 insertion(+), 53 deletions(-)

diff --git a/Documentation/git-rev-list.txt b/Documentation/git-rev-list.txt
index 9392760b25..025c911436 100644
--- a/Documentation/git-rev-list.txt
+++ b/Documentation/git-rev-list.txt
@@ -9,59 +9,7 @@ git-rev-list - Lists commit objects in reverse chronological order
 SYNOPSIS
 --------
 [verse]
-'git rev-list' [ --max-count=<number> ]
-	     [ --skip=<number> ]
-	     [ --max-age=<timestamp> ]
-	     [ --min-age=<timestamp> ]
-	     [ --sparse ]
-	     [ --merges ]
-	     [ --no-merges ]
-	     [ --min-parents=<number> ]
-	     [ --no-min-parents ]
-	     [ --max-parents=<number> ]
-	     [ --no-max-parents ]
-	     [ --first-parent ]
-	     [ --remove-empty ]
-	     [ --full-history ]
-	     [ --not ]
-	     [ --all ]
-	     [ --branches[=<pattern>] ]
-	     [ --tags[=<pattern>] ]
-	     [ --remotes[=<pattern>] ]
-	     [ --glob=<glob-pattern> ]
-	     [ --ignore-missing ]
-	     [ --stdin ]
-	     [ --quiet ]
-	     [ --topo-order ]
-	     [ --parents ]
-	     [ --timestamp ]
-	     [ --left-right ]
-	     [ --left-only ]
-	     [ --right-only ]
-	     [ --cherry-mark ]
-	     [ --cherry-pick ]
-	     [ --encoding=<encoding> ]
-	     [ --(author|committer|grep)=<pattern> ]
-	     [ --regexp-ignore-case | -i ]
-	     [ --extended-regexp | -E ]
-	     [ --fixed-strings | -F ]
-	     [ --date=<format>]
-	     [ [ --objects | --objects-edge | --objects-edge-aggressive ]
-	       [ --unpacked ]
-	       [ --object-names | --no-object-names ]
-	       [ --filter=<filter-spec> [ --filter-print-omitted ] ] ]
-	     [ --missing=<missing-action> ]
-	     [ --pretty | --header ]
-	     [ --bisect ]
-	     [ --bisect-vars ]
-	     [ --bisect-all ]
-	     [ --merge ]
-	     [ --reverse ]
-	     [ --walk-reflogs ]
-	     [ --no-walk ] [ --do-walk ]
-	     [ --count ]
-	     [ --use-bitmap-index ]
-	     <commit>... [ \-- <paths>... ]
+'git rev-list' [<options>] <commit>... [[--] <path>...]
 
 DESCRIPTION
 -----------
-- 
2.23.0.687.g391267506c

Re: [PATCH] git-rev-list.txt: prune options in synopsis

[Junio C Hamano]

Denton Liu <liu.denton@gmail.com> writes:

> The synopsis section in git-rev-list.txt has grown to be a huge list
> that probably needs its own synopsis. Since the list is huge, users may
> be given the false impression that the list is complete, however it is
> not. It is missing many of the available options.
>
> Since the list of options in the synopsis is not only annoying but
> actively harmful, replace it with `[<options>]` so users know to
> explicitly look through the documentation for further information.

I am not sure listing only the most often used ones is harmful.  It
indeed is annoying and it is a good idea to shrink it down like this
patch does.

Thanks.

Re: [PATCH] git-rev-list.txt: prune options in synopsis

[Jeff King]

On Fri, Oct 04, 2019 at 05:13:08PM -0700, Denton Liu wrote:

> The synopsis section in git-rev-list.txt has grown to be a huge list
> that probably needs its own synopsis. Since the list is huge, users may
> be given the false impression that the list is complete, however it is
> not. It is missing many of the available options.
> 
> Since the list of options in the synopsis is not only annoying but
> actively harmful, replace it with `[<options>]` so users know to
> explicitly look through the documentation for further information.
> 
> While we're at it, update the optional path notation so that it is more
> modern.

Yes, thank you! This has bugged me for a while. I suspect there are
other pages that could use similar treatment, but I don't mind at all
doing it incrementally.

(One of them is git-branch, where I think the synopsis should focus on
showing the major modes and not listing every possible branch-listing
option).

-Peff

Re: [PATCH] git-rev-list.txt: prune options in synopsis

[Philip Oakley]

On 11/10/2019 07:04, Jeff King wrote:
> On Fri, Oct 04, 2019 at 05:13:08PM -0700, Denton Liu wrote:
>
>> The synopsis section in git-rev-list.txt has grown to be a huge list
>> that probably needs its own synopsis. Since the list is huge, users may
>> be given the false impression that the list is complete, however it is
>> not. It is missing many of the available options.
>>
>> Since the list of options in the synopsis is not only annoying but
>> actively harmful, replace it with `[<options>]` so users know to
>> explicitly look through the documentation for further information.
>>
>> While we're at it, update the optional path notation so that it is more
>> modern.
> Yes, thank you! This has bugged me for a while. I suspect there are
> other pages that could use similar treatment, but I don't mind at all
> doing it incrementally.
>
> (One of them is git-branch, where I think the synopsis should focus on
> showing the major modes and not listing every possible branch-listing
> option).
>
> -Peff
I'd agree that simplifying the rev-list page is good.

Another case, of a different style, is that of `git bundle --all` which 
does need mentioning that particular rev-list option as a major usage (I 
couldn't manage to understand the three layers of man page that needed 
reading).

I had proposed a patch many years ago [1] but the feedback wasn't 
positive, though my SO question continues [2] to get votes.

Philip

[1] 
https://public-inbox.org/git/1348010734-664-2-git-send-email-philipoakley@iee.org/
[2] 
https://stackoverflow.com/questions/11792671/how-to-git-bundle-a-complete-repo

Re: [PATCH] git-rev-list.txt: prune options in synopsis

[Jeff King]

On Fri, Oct 11, 2019 at 05:02:33PM +0100, Philip Oakley wrote:

> Another case, of a different style, is that of `git bundle --all` which does
> need mentioning that particular rev-list option as a major usage (I couldn't
> manage to understand the three layers of man page that needed reading).
> 
> I had proposed a patch many years ago [1] but the feedback wasn't positive,
> though my SO question continues [2] to get votes.

Yeah, I agree that "git bundle" could be more clear about this. I think
just adding an example like this might help:

  # generate a bundle similar to what "git clone" would produce
  git bundle create file.bundle --branches --tags

-Peff