Inconsistency with -a vs -A

Inconsistency with -a vs -A

[Bradly Feeley]

I was curious if there was a reason that some command use -a and some command
use -A. For example, to view all branches the lowercase switch 'a' is used, but
when staging all files with add an uppercase 'A'. Of course I always pick the
wrong one when running either command. Is there a reason for the inconsistency?
Do you think they should be made the same?

Thanks!
Bradly Feeley

Re: Inconsistency with -a vs -A

[Michael J Gruber]

Bradly Feeley venit, vidit, dixit 18.04.2011 05:20:
> I was curious if there was a reason that some command use -a and some command
> use -A. For example, to view all branches the lowercase switch 'a' is used, but
> when staging all files with add an uppercase 'A'. Of course I always pick the
> wrong one when running either command. Is there a reason for the inconsistency?

Yes.

> Do you think they should be made the same?

Yes, I do :) For more details on both "yes", see:

http://permalink.gmane.org/gmane.comp.version-control.git/167907

Cheers,
Michael

Re: Inconsistency with -a vs -A

[Junio C Hamano]

Bradly Feeley <bradlyf@gmail.com> writes:

> I was curious if there was a reason that some command use -a and some command
> use -A.

In the context of SCM, the word "all" is unfortunately ambiguous. In most
cases, when you say "all", you do not mean everything under the sun, but
only mean the tracked subset of everything.

For example, "commit -a" only includes the paths that have been tracked,
and grabs the up-to-date contents in them in your working tree. It does
not add paths that have been untracked to the set of tracked paths. This
was historically useful because we started out without a good .gitignore
support and "commit ." is not "everything" when run from a subdirectory.

Also many commands (e.g. "git diff", "git grep") work on "all tracked"
when you do not explicitly name what to operate on.  Even when you specify
what subset to operate on, that subset is still taken from "all tracked",
not "everything in the working tree" (e.g. "git grep -e frotz ." does not
look into any untracked paths).

When you think about "tracked" vs "untracked", you would realize that
"add" is and has to be an oddball. It is the primary mechanism to start
tracking hitherto untracked paths.  For this reason, "git add ." has to
look at untracked paths and add them (contrast this with the "git grep"
example above).

We named the "update contents for all tracked paths" option "-u", avoiding
to say "-a" on purpose, because "all" is an ambiguous word, especially in
the context of "git add" command.  It perhaps was being overly cautious in
hindsight.

One important case to think about is that "git commit -a". Most commands
limit the set of paths they operate on from all tracked paths, and this
command has to mean "take the up-to-date contents from all tracked files
and make a commit".  So does "git commit ." run from the top-level of the
tree.

Now, what if you have a bunch of hitherto untracked paths, have a well
maintained .gitignore file, want to add and commit them, and want to be
lazy (i.e. you hate that "git add . && git commit" are two commands)?
There needs a way to say "everything under the sun" to please such people.

That is where "git commit -A" came from. "add -A" is an option that is
unnecessary ("git add ." would do just fine), but was added to give a
warm-fuzzy feel of consistency between "commit" and "add", in preparation
of the planned addition of "git commit -A" that didn't happen.

The only uppercase "-A" I am aware of are these two, and both are about
"everything under the sun", which is a special case in the context of SCM.
All the other usual "all" options are spelled "-a".

I think we could give "add -a" as a synonym to "add -u", which would be a
safe addition that would not break any existing user, if we wanted to be
picky and really make things more consistent.

Also in the longer term, I suspect we probably should deprecate "add -A"
as a failed experiment, if we are not going to do "commit -A" after all.
"add ." and "add :/" (from a subdirectory) would be much less ambiguous,
and it will get rid of the only instance of "-A" that means something
slightly different from the usual "all".

Re: Inconsistency with -a vs -A

[Junio C Hamano]

Junio C Hamano <gitster@pobox.com> writes:

> The only uppercase "-A" I am aware of are these two, and both are about
> "everything under the sun", which is a special case in the context of SCM.
> All the other usual "all" options are spelled "-a".
>
> I think we could give "add -a" as a synonym to "add -u", which would be a
> safe addition that would not break any existing user, if we wanted to be
> picky and really make things more consistent.
>
> Also in the longer term, I suspect we probably should deprecate "add -A"
> as a failed experiment, if we are not going to do "commit -A" after all.
> "add ." and "add :/" (from a subdirectory) would be much less ambiguous,
> and it will get rid of the only instance of "-A" that means something
> slightly different from the usual "all".

The last paragraph is really "in the _longer_ term".  Two things need to
happen before we get there:

 - we need to teach "add ." or with any pathspec to do what the current
   "-A" with the same pathspec does implicitly, while keeping "add"
   without any pathspec a no-op.

 - ":/" (from root, whole tree) needs to be added.  We already know how
   that pathspec will behave and how to implement it.

The former may need a bit of thought and discussion, but I personally
think that "git add" with pathspec should notice deletion of tracked
paths.  It may have been Ok back when "git add $path" was only for adding
new paths, but we have changed from that semantics a long time ago and the
command deals with both tracked and untracked paths.  It does not make
much sense to special case tracked but removed paths anymore [*1*]

The latter we know we will have in a release or two.


[Footnote]

* The code does not do any special casing at the design level, but they
fall within the cracks of the implementation.