Re: [PATCH] Documentation: explain "git branch --with"

Jonathan Nieder <jrnieder@gmail.com> writes:

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

... for the first time is bound to ask what the differences are between the two.