[1.8.0 RFD] Homogeneous use of short options

[1.8.0 RFD] Homogeneous use of short options

[Michael J Gruber]

Proposal:
Make our use of short options more homogeneous.

I have put together a list of options which are used by the "most common
commands", using the output of "git --help-all":

http://repo.or.cz/w/git/mjg.git/blob/options.txt

(scroll down for the short options)

This leaves out a few commands with different option parsing (diff, log,
rebase, show) but indicates that we're doing a good job already. A few
notable outliers:

add -A: Why capital A? Compare commit -a etc.

commit -n, fetch -n, merge -n: These are REALLY bad! Users should be
able to rely on '-n' being '--dry-run' or at least being no-op to their
repo, like clone/grep/tag -n.

tag -v: This is not a real problem, but users have certain expections
for "-f,-h,-n,-v" which we should break as rarely as possible. OTOH,
what would "verbose" mean for tag? (NB: tag.txt is grossly wrong.)

grep -?: This tries to be compatible with GNU grep, so it's a natural
outlier.

Risks:
Users and scripts may obviously depend on the current options names.

Migration plan:
Introduce new options first (1.7.x) along with warnings in the release
notes (optionally, make the commands output warnings). Then change the
behavior in 1.8.0.

TODO:
Generate an option list for the other common commands.

I'll also follow up with a little series fixing inconsistencies in the
descriptions.

Re: [1.8.0 RFD] Homogeneous use of short options

[Nguyen Thai Ngoc Duy]

On Mon, Feb 14, 2011 at 10:04 PM, Michael J Gruber
<git@drmicha.warpmail.net> wrote:
> Proposal:
> Make our use of short options more homogeneous.
>
> ...
>
> Risks:
> Users and scripts may obviously depend on the current options names.
>
> Migration plan:
> Introduce new options first (1.7.x) along with warnings in the release
> notes (optionally, make the commands output warnings). Then change the
> behavior in 1.8.0.

Sometimes I think we could just add a new "root" name for total UI
redesign. Say all commands starting with "gic" (or whatever name it
is, "gt" may be even shorter) will have new/consistent behavior while
"git" ones remain unchanged (or changed gradually and sloooowly). It
happened with bazaar (baz vs bzr) long ago.
-- 
Duy

Re: [1.8.0 RFD] Homogeneous use of short options

[Jay Soffian]

On Mon, Feb 14, 2011 at 10:04 AM, Michael J Gruber
<git@drmicha.warpmail.net> wrote:
> tag -v: This is not a real problem, but users have certain expections
> for "-f,-h,-n,-v" which we should break as rarely as possible. OTOH,
> what would "verbose" mean for tag? (NB: tag.txt is grossly wrong.)

I made mine look like branch -v:

$ cat bin/git-tagv
#!/bin/sh
format='
case %(objecttype) in
  commit)
    sha1=%(objectname:short)
    subject=%(subject)
    ;;
  tag)
    sha1=%(*objectname:short)
    subject=%(*subject)
    ;;
esac
printf "%s\t%s\t%s\n" %(refname:short) "$sha1" "$subject"
'
eval "$(git for-each-ref --shell --format="$format" refs/tags)" |
column -t -s "$(printf '\t')"

j.

Re: [1.8.0 RFD] Homogeneous use of short options

[Junio C Hamano]

On Mon, Feb 14, 2011 at 7:04 AM, Michael J Gruber
<git@drmicha.warpmail.net> wrote:

> add -A: Why capital A? Compare commit -a etc.

IIRC, this was in anticipation for a similar interface to include
_new_ files in the commit in the form of "commit -A", which _is_
different from the existing "commit -a".

Re: [1.8.0 RFD] Homogeneous use of short options

[Miles Bader]

Junio C Hamano <gitster@pobox.com> writes:
>> add -A: Why capital A? Compare commit -a etc.
>
> IIRC, this was in anticipation for a similar interface to include
> _new_ files in the commit in the form of "commit -A", which _is_
> different from the existing "commit -a".

I look up the meaning of "git commit -u":

$ git commit --help
...
       -u[<mode>], --untracked-files[=<mode>]
           Show untracked files (Default: all).

           The mode parameter is optional, and is used to specify the handling
           of untracked files.

           The possible options are:

           ·    no - Show no untracked files
           ·    normal - Shows untracked files and directories
           ·    all - Also shows individual files in untracked directories.

               See git-config(1) for configuration variable used to change the
               default for when the option is not specified.

I guess it means it only affects the status-display for --dry-run, but
it seems a little confusing to not say that explicitly...

-miles

-- 
Cabbage, n. A familiar kitchen-garden vegetable about as large and wise as a
man's head.

Re: [1.8.0 RFD] Homogeneous use of short options

[Michael J Gruber]

Miles Bader venit, vidit, dixit 15.02.2011 01:52:
> Junio C Hamano <gitster@pobox.com> writes:
>>> add -A: Why capital A? Compare commit -a etc.
>>
>> IIRC, this was in anticipation for a similar interface to include
>> _new_ files in the commit in the form of "commit -A", which _is_
>> different from the existing "commit -a".
> 
> I look up the meaning of "git commit -u":
> 
> $ git commit --help
> ...
>        -u[<mode>], --untracked-files[=<mode>]
>            Show untracked files (Default: all).
> 
>            The mode parameter is optional, and is used to specify the handling
>            of untracked files.
> 
>            The possible options are:
> 
>            ·    no - Show no untracked files
>            ·    normal - Shows untracked files and directories
>            ·    all - Also shows individual files in untracked directories.
> 
>                See git-config(1) for configuration variable used to change the
>                default for when the option is not specified.
> 
> I guess it means it only affects the status-display for --dry-run, but
> it seems a little confusing to not say that explicitly...

I think it is confusing only until you have used "commit" without "-m"
for the first time - and only if you overlooked the 3 occurences of
"show" ;)

Michael