Inconsistency with -a vs -A

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

Bradly Feeley venit, vidit, dixit 18.04.2011 05:20:

Yes.

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

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

Cheers, Michael

Bradly Feeley <bradlyf@gmail.com> writes:

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

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

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.