| Message ID | 645cc54c4c86493c855ec6b0b892a0bc8e999249.1570234118.git.liu.denton@gmail.com (mailing list archive) |
|---|---|
| State | New, archived |
| Headers | show |
| Series | git-rev-list.txt: prune options in synopsis | expand |
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.
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
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
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
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 -----------
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(-)