Jonathan Nieder <jrnieder@xxxxxxxxx> writes: > More precisely, it is advertised by "git branch --help-all" but not > the manual or "git branch -h". Sorry, but I don't understand what you are trying to say here. Isn't it the whole point of distinction between --help-all vs -h (aka PARSE_OPT_HIDDEN)? Some interesting findings after a quick "grep" to see which ones are hidden (potential bugs below might be good for janitors). * apply --allow-binary-replacement, --binary These are always on, and are no-op (even --no-binary is a no-op); documented. * archive -[2-8] git-archive manual page mentions -0 thru -9 can be used as "zip backend option", while explicitly describing -0 and -9. "git archive -h" gives special description for -1 as well. Perhaps we should be consistent and document -1 in the manual page. * checkout --[no-]guess Controls the "dwim 'git checkout x' to 'git checkout -b x remote/x' when 'x' cannot possibly name anything other than a branch that we copied from a remote repository uniquely"; since the dwimming is on by default, the only use case is to say --no-guess; not documented. * clone --naked An old name used during the development for the current --bare option; not documented. * commit --allow-empty --allow-empty-message Documented; hidden primarily to discourage their uses and also to keep output from 'commit -h' short. * fmt-merge-msg --summary An old name used during the development for the current --log option; documented. * grep --help-all, show-ref --help-all I do not know why an entry for this needs to be in the struct option [] for the command. It is not (and should not be) documented in the manual page of the individual commands. * show-ref -h "-h" was meant to be a historical synonym for "--head" (i.e. tells the command include HEAD in the output not just under refs/ hierarchy), but it seems that we broke it somewhere between v1.6.5 and v1.7.0; it now shows the help text. * write-tree --ignore-cache-tree A debugging aid; not documented. It seems that our use of OPT_HIDDEN or if a hidden option is documented are not entirely consistent. The "--with" under discussion is similar to "clone --naked" and "fmt-merge-msg --summary". I am Ok with a policy to document historical synonyms that are hidden, but if we were to document them, I suspect that we would need to explicitly state they are synonyms. Otherwise, somebody who saw this... > --contains <commit>:: > +--with <commit>:: > Only list branches which contain the specified commit. ... for the first time is bound to ask what the differences are between the two. -- To unsubscribe from this list: send the line "unsubscribe git" in the body of a message to majordomo@xxxxxxxxxxxxxxx More majordomo info at http://vger.kernel.org/majordomo-info.html