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

Jonathan Nieder [off-list ref] 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.