== Yes, _git add_ makes a difference (no matter what people think)

One of the things said about [[git http://git-scm.com/]] is that
it's less user friendly and takes longer to learn than [[Mercurial
http://mercurial.selenic.com/]]; the first exhibit for this difference
is usually _git add_ and by extension git's index.  Unfortunately,
a [[common reaction
http://felipec.wordpress.com/2011/01/16/mercurial-vs-git-its-all-in-the-branches/]]
among git fans to both the general issue and _git add_ in specific
is a kind of defensive denial, where they hold forth that it's not
that difficult and people learn it fine and really, git is user
friendly.

You may already have gotten an idea of my views on this. I'm here to
tell you, from a mostly outsider perspective, that _git add_ really
does make a real difference in initial user friendliness, one that
makes Mercurial easier to pick up and use for [[straightforward uses
../sysadmin/MercurialVsGit]].

(I've used git to a certain extent, for example for [[my Github stuff
https://github.com/siebenmann/]], but I am not up to the experienced
user level. I'm not really at that level with Mercurial either, partly
because I haven't needed to be and partly because I'd rather learn git;
Mercurial is easier but I like git more.)

Before people freak out too much, let me be explicit: all of this is
about *initial user friendliness*, the ease of doing straightforward
things and picking up the system. In the long run I think that the
git index is the right design decision (for a programmer focused VCS)
because it creates an explicit model for doing a number of important
but tricky things, a model that can be manipulated and inspected and
reasoned about, and once you learn git and use it regularly dealing with
the index becomes second nature.  But people generally do not defend the
index in these terms; instead, they try to maintain with a straight face
that it's no real problem for people even at the start.

(If you think that the index does not cause problems for git beginners,
I would gently suggest that you trawl through some places where they ask
questions.)

The usability problem with _git add_ is not just the need for _git
add_ itself as an extra step, it is that the existence of the index
has additional consequences that ripple through to using other bits of
git. For example, let us take the case of the disappearing diff:

>  ; git diff a
>  [...]
>  -hi there
>  +hi there, jim
>  ; git add a
>  ; git diff
>  ;

If you already know git you know what's going on here (and you're going
to reach for '_git diff --cached_'). If you're learning git, well, your
change just disappeared. Of course this happens the other way around
too; '_git diff_' shows you nice diffs, then you do '_git commit_' and
it tells you nothing to commit. Wait, what? The diffs are right there.

(There's worse bear traps in the woods for beginners, too, like doing a
'_git add_' and then further editing the file. Here '_git diff_' will
show you a diff but it is *not* what will be committed.)

~~All of this is a cognitive burden~~. When you use git, you have to
learn and remember the existence of the index and how this affects what
you do, and you probably need to take extra steps or pay extra attention
to what '_git commit_' and so on tell you. This cognitive burden is
real, although it can (and will be) overcome with familiarity and what
it enables has important benefits.  It is a mistake and a lie to try to
pretend otherwise. Honesty in git advocacy is to say straightforwardly
that the index is worth it in the end (possibly unless you have [[simple
work patterns ../sysadmin/MercurialVsGit]]).

(A system where the index or its equivalent is an advanced feature, one
not exposed by default, really does have a simpler initial workflow. If
it's designed competently (and Mercurial is), everything 'just works'
the way you expect; _hg commit_ commits what _hg diff_ shows you and so
on. In real life this makes a difference to people's initial acceptance
of a new VCS, especially if the simple workflow is adequate for almost
everything you'll ever do with the system. This is not true of the sort
of advanced VCS use that programmers can practice routinely, but [[it can
be of other VCS uses ../sysadmin/SysadminVCSUse]].)

=== Sidebar: the problem with '_git commit -a_'

At this point some people may come out of the woodwork to tell me about
_git commit -a_, or even about creating an alias like '_git checkin_'
that always forces _-a_. There are two pragmatic problems with this.

First, the index still exists even if you're trying to pretend otherwise.
This means that you can accidentally use the index; you can run _git add_
because something said to, or you can run straight _git commit_, and so on.
All of these will create confusion and cause git to do what (to you) looks
like the wrong thing.

(In fact you have to run _git add_ every so often, to add new files.)

Second, it is not at all obvious from simply reading documentation that
using _git commit -a_ is a fully reliable way of transmuting git into
Mercurial. Maybe it is, maybe it isn't, but as a beginner you don't
know (not without doing more research than I myself have done). Because
many git operations are fundamentally built around the existence of
the index, the safest assumption to make is that the index really does
matter and _git commit -a_ is probably an incomplete workaround.

(For example, at the point where you do _git add_ to add a new file
you'll become familiar with _git diff HEAD_ in order to get the true
diffs for what will be committed when you run _git commit -a_, which I
hope illustrates my point adequately. And maybe there's a better command
for doing that, which *also* illustrates my point because _git diff HEAD_
is what I came up with as a relative git novice.)