[PATCH v2 00/12] merge summary and diffstat options cleanup

["SZEDER Gábor" <szeder@ira.uka.de>]

On Sat, Apr 05, 2008 at 07:36:57PM -0700, Junio C Hamano wrote:
> ...this hunk removes the original options from OPTIONS_SPEC, I suspect you
> would get "unknown option 'stat'" from underlying "git rev-parse --parseopt".
> 
> You probably haven't noticed the breakage because you replaced all
> existing --summary with --stat in the tests, though.  Oops.
It was not clear to me that this OPTIONS_SPEC is used for parsing,
too.  This series fixes the problem.

> We would want to take a three-stage approach where we (1) start accepting
> both forms without changing the official names shown to the users, (2)
> deprecate the old names and make the new ones official, and then (3)
> finally remove the old ones.  Your 2 thru 5 roll (1) and (2) into one
> step.
> 
> I would not have major problem with this "hasty deprecation" in "usage"
> strings, but I find it somewhat problematic to stop mentioning the old
> names in the documentation and bash completion from day one.  People learn
> old names elsewhere (e.g. in somebody's blog entry) and then try to find
> the description in their manual and they are already removed from your
> copy.  Oops.
Yeah, you are right that deprecated options should not be removed from
the documentation.

However, I think that rolling (1) and (2) into one step is better than
having them separate.  If we have the two steps separate will also
cause confusion, as users learning merge & co. between (1) and (2) 
might wonder, why are there two options for the same thing and which
one should they prefer.  They might even suspect that one of the 
options will be deprecated in the future, but they will not be able to
tell which without looking at e.g. the mailing list archives.  I would
also prefer to remove the deprecated options and config variables from
bash completion, because their users will then notice earlier that the
options are deprecated.

But anyway, in this patch series steps (1) and (2) are split into
separate set of patches, so you can decide to have steps (1) and (2)
separately or not.

The first six patches are adding the new options and config variables
to merge, pull, and fmt-merge-msg, but are not deprecating the old
ones.  They are also updating documentation, tests, and bash
completion accordingly.  (Patches 1 and 4 are independent cleanups
that could be merged regardless of the other patches, but the others
are depending on them.)

Patches 7-9 are marking the old options and config variables as
deprecated.

And finally, patches 10-12 are removing all the deprecated stuff, but
they are there only for illustration purposes at the moment, to see
how things will look like after the deprecation period.


SZEDER Gábor (12):
  doc: moved merge.* config variables into separate merge-config.txt
  merge, pull: introduce '--(no-)stat' options
  add 'merge.stat' config variable
  t6200-fmt-merge-msg: put expected messages into different files
  fmt-merge-msg: add '--(no-)log' options and 'merge.log' config
    variable
  merge, pull: add '--(no-)log' command line option
  merge, pull: mark '--(no-)summary' options as deprecated
  merge, pull: mark the config variable 'merge.diffstat' as deprecated
  fmt-merge-msg: mark summary-related option and config variable as
    deprecated
  merge, pull: remove deprecated '--(no-)summary' options
  merge, pull: remove deprecated 'merge.diffstat' config variable
  fmt-merge-msg: remove deprecated summary-related options and config
    variable

 Documentation/config.txt               |   32 +------------------
 Documentation/git-fmt-merge-msg.txt    |   10 +++---
 Documentation/git-merge.txt            |   17 ++--------
 Documentation/merge-config.txt         |   35 ++++++++++++++++++++
 Documentation/merge-options.txt        |   15 +++++++--
 builtin-fmt-merge-msg.c                |    8 ++--
 contrib/completion/git-completion.bash |    6 ++-
 git-merge.sh                           |   18 ++++++----
 git-pull.sh                            |   20 ++++++------
 t/t6200-fmt-merge-msg.sh               |   54 ++++++++++++++++++++++++-------
 t/t7600-merge.sh                       |   24 +++++++++++---
 11 files changed, 146 insertions(+), 93 deletions(-)
 create mode 100644 Documentation/merge-config.txt