Git terminology: remote, add, track, stage, etc.

Git terminology: remote, add, track, stage, etc.

[Thore Husfeldt]

I’ve just learned Git. What a wonderful system, thanks for building
it. 

And what an annoying learning experience. 

I promised myself to try to remember what made it all so hard, and to
write it down in a comprehensive and possibly even constructive
fashion. Here it is, for what it’s worth. Read it as the friendly, but
somewhat exasparated suggestions of a newcomer. I’d love to help (in
the form of submitting patches to the documentation or CLI responses),
but I’d like to test the waters first.

So, in no particular order, here are the highlights of my former
confusion, if only for your entertainment. Comments are welcome, in
particular where my suggestions are born out of ignorance.

Remote (tracking) branches
--------------------------

There are at least two uses of the word *tracking* in Git's
terminology.

The first, used in the form “git tracks a file” (in the sense that Git
knows about the file) is harmless enough, and is handled under `git
add` below.

But the real monster is the *tracking branch*, sometimes called the
remote branch, the remote-tracking branch, or the remote tracking
branch. Boy did that ever confuse me. And, reading the git mailing
list and the web, many others. There are so many things wrong with how
this simple concept is obfuscated by the documentation that I have a
hard time organising my thoughts about writing it down.

Please, *please* fix this. It was the single most confusing and
annoying part of learning Git.

First, the word, “tracking”. These branches don’t track or follow
anything. They are standing completely still. Please believe me that
when first you are led to believe that origin/master tracks a branch
on the remote (like a hound tracks it quarry, or a radar tracks a
flight) that it is very difficult to hunt this misunderstanding down:
I believed for a long time that the tracking branch stayed in sync,
automagically, with a synonymous branch at the remote. The CLI and
documentation worked very hard to keep me in that state of
ignorance. I *know* that my colleague just updated the remote
repository, yet the remote branch (or is the remote tracking branch?
or the remote-tracking branch?) is as it always was...? (How could I
*ever* believe that? Well, *now* I get it, and have a difficult time
recollecting that misunderstanding. *Now* it’s easy.)

Second, the word “remote” as opposed to “local”, a dichotomy enforced
by both the documentation and by the output of `git branch -r` (list
all remote branches, says user-manual.txt). Things began to dawn on me
only when I understood that origin/master is certainly and absolutely
a “local” branch, in the sense that it points to a commit in my local
repository. (It differs from my other local branches mainly in how it
is updated. It’s not committed to, but fetched to. But both are local,
and the remote can be many commits ahead of me.)

So, remote tracking branches are neither remote (they are *local*
copies of how the remote once was) and they stand completely still
until you tell them to “fetch”. So remote means local, and tracking
means still, “local still-standing” would be a less confusing term
that “remote tracking”. Lovely.

Tracking branches *track* in the sense that a stuffed Basset Hound
tracks. Namely, not. It‘s a dream of what once was.

The hyphenated *remote-tracking* is a lot better terminology already
(and sometimes even used in the documentation), because at least it
doesn't pretend to be a remote branch (`git branch -r`, of course,
still does). So that single hyphen already does some good, and should
be edited for consistency. (It did take time for me to convince myself
during the learning process that “remote tracking” and
“remote-tracking” probably are the same thing, and “tracked remote”
something else, abandoning and resurrecting these hypetheses several
times.)

And *even if* the word was meaningful and consistenly spelt, the
documentation uses it to *refer* to different things. Assume that we
have the branches master, origin/master, and origin’s master
(understanding that they exist, and are different, is another Aha!
moment largely prevented by the documentation). For 50 points, which
is the remote tracking branch? Or the remote-tracking branch? The
remote branch? Which branch tracks which other branch? Does master
track anything? Nobody seems to know, and documentation and CLI
include various inconsistent suggestions. (I know there have been
long, and inconclusive threads about this on the git mailing list, and
I learned a lot from seeing other people’s misconceptions mirror my
own.)  Granted, I think the term “tracked remote branch” is used with
laudable consistentcy to refer to a branch on the remote. And “remote
tracking branch” (with our without the hyphen) more often than not
refers to origin/master. It may be that terminology is slowly
converging. (To something confusing, but still...)

But to appreciate how incredibly difficult this was to understand,
check this, from the Git Community book:

    A 'tracking branch' in Git is a local branch that is connected to
    a remote branch.

To a new user, who *almost* gets it, this is just a slap in the
face. Which one of these is origin/master again? None? (Or rather, it
is the confirmation one needs that nobody in the Git community cares
much, so the once-believed-to-be-carefully-worded documentation loses
some of its authority and therefore the learner can abandon some
misunderstandings.)

There probably is a radical case to be made for abandoning the word
“tracking” entirely. First, because tracking branches don’t track, and
second because “tracking” already means something else in Git (see
below). I realise that this terminology is now so ingrained in Git
users that conservatism will probably perpetuate it. But it would be
*very* helpful to think this through, and at least agree on who
“tracks” what. In the ideal world, origin/master would be something
like “the fetching branch” for the origin’s master, or the “snapshot
branch” or the “fetched branch”. (I am partial to use “fetching”
because it makes that operation a first-class conceptual citizen,
rather than pulling, which is another siren that lures newbies into a
maelstroem of confusion.)

More radically, I am sure some head scratching would be able to find
useful terminology for master, origin/master, and origin’s master. I’d
love to see suggestions. As I said, I admire how wonderfully simple
and clean this has been implemented, and the documentation, CLI, and
terminology should reflect that.

The staging area
----------------

The wonderful and central concept of staging area exists under at
least three names in Git terminology. And that’s really, really
annoying. The index, the cache, and the staging area are all the same,
which is a huge revelation to a newcomer.

This problem could of course be easily fixed by making up your
mind. The decision which of the three terms to adopt is somewhat
arbitrary, but *staging area* gives the strongest and best
metaphor. It also verb quite well, even though it is not the best,
shortest noun. *Index* would have been a good word for the files known
to Git (what is now called, sometimes, “tracked files”), and *cache*
is terrible in any case.

`git stage` is already part of the distribution. Great.

1. Search for index and cache in the documentation and rephrase any
and all their occurences to use “staged” (or, if it can’t be avoided
“the staging area”) instead. Say “staged to be committed” often, it’s
a strong metaphor.

2. Introduce the alias `git unstage` for `git reset HEAD` in the
standard distribution.

3. Duplicate various occurences of `cached` flags as `staged` (and
change the documentation and man pages accordingly), so as to have,
e.g., `git diff --staged`.

git status
----------

One of the earliest-to-use commands is `git status`, whose message are
*wordy*, but were initially completely unhelpful to me. In particular,

   working directory clean

Clean? What’s this now? Clean and dirty are Git slang, and not what I
want to meet as a new user. The message should inform me that the
untracked files in the working directory are equal to their previous
commit. But there are other things wrong with the message. For
example, even though there’s nothing to commit: `nothing added to
commit but untracked files present (use "git add" to track)`? The last
paranethesis should set off warning bells already. And what did clean
mean with respect to untracked files? And “added to commmit”? That
sounds like amending. We add to the index or the staging area, don’t
we, “ready to be included in the next commit,” so they aren’t added to
that commit quite yet?

    changed but not updated:

I’m still not sure what “update” was ever supposed to mean in this
sentence. I just edited the file, so it’s updated, for crying out
loud! The message might just say “Changed files, but not staged to be
committed.”  The meant-to-be helpful “use [...] to update what will be
committed” is another can of worms, and I can find at least two ways
to completely misunderstand this. Change to “use `git stage <file>` to
stage”. (With the new command name it’s almost superfluous.)
  
Here are some concrete suggestions:

1.

    nothing added to commit but untracked files present

should be

    nothing staged to commit, but untracked files present

(Comment: maybe “... but working directory contains untracked files.”
I realise that “directory” is not quite comprehensive here, because
files can reside in subdirectories. But I’d like to be more concrete
than “be present”.)

2.
    Untracked files:
    (use "git add <file>..." to include in what will be committed)

should be

    Untracked files:
    (use "git track <file>" to track)

3.

    Changes to be committed:
    (use "git reset HEAD <file>..." to unstage)

should be

    Staged to be committed:		 
    (use "git unstage <file>" to unstage)

Adding
------

The tutorial tells us that 

    Many revision control systems provide an add command that tells
    the system to start tracking changes to a new file. Git's add
    command does something simpler and more powerful: git add is used
    both for new and newly modified files, and in both cases it takes
    a snapshot of the given files and stages that content in the
    index, ready for inclusion in the next commit.

This is true, and once you grok how Git actually works it also makes
complete sense. “Making the file known to Git” (sometimes called
“tracking the file”) and “staging for the next commit” result in the
exact same operations, from Git’s perspective.

But this is a good example of what’s wrong with the way the
documentation thinks: Git’s implementation perspective should not
define how concepts are explained. In particular, *tracking* (in the
sense of making a file known to git) and *staging* are conceptually
different things. In fact, the two things remain conceptually
different later on: un-tracking (removing the file from Git’s
worldview) and un-staging are not the same thing at all, neither
conceptually nor implementationally. The opposite of staging is `git
reset HEAD <file>` and the opposite of tracking is -- well, I’m not
sure, actually. Maybe `git update-index --force-remove <filename>`?
But this only strenghtens my point: tracking and staging are different
concepts, and therefore deserve different terms in the documentation
and (ideally) in the CLI.

The entire quoted paragraph in the tutorial can be removed: there’s
simply no reason to tell the reader that git behaves differently from
other version control systems (indeed, to take some perverse *pride*
in that fact). 

Fixing this requires no change to the implementation. `git stage` is
already a synonym for `git add`. It merely requires discipline in
using the terminology of staging. Note that it completely valid to
tell the reader, maybe immediately and in a footnote, that `git add`
and `git stage` *are* indeed synonyms, because of Git’s elegant
model. In fact, given the amount of documentation cruft one can find
on the Internet, this would be a welcome footnote.

An even more radical suggestion (which would take all of 20 seconds to
implement) is to introduce `git track` as another alias for `git
add`. (See above under `git status`). This would be especially useful
if tracking *branches* no longer existed.

There’s another issue with this, namely that “added files are
immediately staged”. In fact, I do understand why Git does that, but
conceptually it’s pure evil: one of the conceptual conrnerstones of
Git -- that files can be tracked and changed yet not staged, i.e., the
staging areas is conceptually a first-class citizen -- is violated
every time a new file is “born”. Newborn files are *special* until
their first commit, and that’s a shame, because the first thing the
new file (and, vicariously, the new user) experiences is an
aberration. I admit that I have not thought this through.

Re: Git terminology: remote, add, track, stage, etc.

[Jonathan Nieder]

Hi Thore,

Thore Husfeldt wrote:

>     what an annoying learning experience. 
> 
> I promised myself to try to remember what made it all so hard, and to
> write it down in a comprehensive and possibly even constructive
> fashion.

Thanks for doing this work!

> There probably is a radical case to be made for abandoning the word
> “tracking” entirely. First, because tracking branches don’t track, and
> second because “tracking” already means something else in Git (see
> below).

I think you are overthinking this "tracking like a Basset hound" thing.

When a person keeps a diary to track their appointments, is it always
up to date?  No, it is only as up to date as the person is diligent.
Similarly, git provides a namespace for branches that a person can
use to track remote branches, which is only as up to date as one
keeps it.

So what would be a better term?

>                In the ideal world, origin/master would be something
> like “the fetching branch” for the origin’s master, or the “snapshot
> branch” or the “fetched branch”.

Familiarity might be leaving me blind, but these all sound even more
confusing to me.  In fact, origin/master is not only updated by
fetching but by pushing (at least if I remember correctly).  It is
meant to be git's local memory of remote content.

Using the term "remote-tracking" consistently would certainly be an
improvement and would make it easier to do a search-and-destroy (erm,
-and-replace) if another term comes up that seems to fit the concept
better.

> The wonderful and central concept of staging area exists under at
> least three names in Git terminology. And that’s really, really
> annoying. The index, the cache, and the staging area are all the same,
> which is a huge revelation to a newcomer.

Heh.  Personally I tend to think in terms of "the index".

e.g., "git add" registers changes for use in the next commit.
Information about the commit in preparation is stored in the
index.

Why?  Because "staging area" has this misleading feeling of
not-jargon.  It is jargon and when misused can be very confusing
(to me, at least).

> 2. Introduce the alias `git unstage` for `git reset HEAD` in the
> standard distribution.

Doesn't "git reset" ('reset the staged content to match...') fit the
same metaphor?

> 3. Duplicate various occurences of `cached` flags as `staged` (and
> change the documentation and man pages accordingly), so as to have,
> e.g., `git diff --staged`.

Already exists (though in practice it tends to be easier to teach
--cached since that is the option that documents all over the web
use).

> Clean? What’s this now? Clean and dirty are Git slang, and not what I
> want to meet as a new user. The message should inform me that the
> untracked files in the working directory are equal to their previous
> commit.

Huh?

Anyway, improvements welcome (in the form of a simple mockup, or even
better, patches).

>     changed but not updated:
> 
> I’m still not sure what “update” was ever supposed to mean in this
> sentence.

It's historical residue.  (What is now done with "git add" used to be
done with "git update-index").

>     Untracked files:
>     (use "git add <file>..." to include in what will be committed)
>
> should be
>
>     Untracked files:
>     (use "git track <file>" to track)

Is this "git track" a synonym for "git add -N"?

>                                      The opposite of staging is `git
> reset HEAD <file>` and the opposite of tracking is -- well, I’m not
> sure, actually.

Ah, this is a kind of obnoxious thing!  For a newly added file,

	git reset -- <path>

ought to un-add it, but it doesn't.

For a file that has been around for a while, removal is imho just
adding a different kind of change.  It would be nice if

	git add -- <path>

pointed to "git rm --cached" to help the operator to do that.

> The entire quoted paragraph in the tutorial can be removed: there’s
> simply no reason to tell the reader that git behaves differently from
> other version control systems

How will a person used to e.g. cvs ever adjust if they don't even
realize git is different?

Hope that helps,
Jonathan

Re: Git terminology: remote, add, track, stage, etc.

[Sverre Rabbelier]

Heya,

[+Scott, who's done a lot of work on making git more newbie friendly]
[+Jonathan, I saw his reply just before sending this]

On Mon, Oct 18, 2010 at 15:45, Thore Husfeldt <thore.husfeldt@gmail.com> wrote:
> I’ve just learned Git. What a wonderful system, thanks for building
> it.

Thanks.

> And what an annoying learning experience.

Thanks again :).

> I promised myself to try to remember what made it all so hard, and to
> write it down in a comprehensive and possibly even constructive
> fashion. Here it is, for what it’s worth. Read it as the friendly, but
> somewhat exasperated suggestions of a newcomer. I’d love to help (in
> the form of submitting patches to the documentation or CLI responses),
> but I’d like to test the waters first.

Awesome! Your experiences are very welcome indeed!

> So, remote tracking branches are neither remote (they are *local*
> copies of how the remote once was) and they stand completely still
> until you tell them to “fetch”. So remote means local, and tracking
> means still, “local still-standing” would be a less confusing term
> that “remote tracking”. Lovely.

*chortles*, nicely observed.

> The hyphenated *remote-tracking* is a lot better terminology already
> (and sometimes even used in the documentation), because at least it
> doesn't pretend to be a remote branch (`git branch -r`, of course,
> still does).

What do you mean with the last part (about `git branch -r`)? The fact
that 'refs/remotes' is not immutable?

> So that single hyphen already does some good, and should
> be edited for consistency.

If we agree that "remote-tracking" is the way to go, a patch doing
such editing would be very welcome.

> And *even if* the word was meaningful and consistently spelt, the
> documentation uses it to *refer* to different things. Assume that we
> have the branches master, origin/master, and origin’s master
> (understanding that they exist, and are different, is another Aha!
> moment largely prevented by the documentation).

How could the documentation make this more clear?

> Or rather, it is the confirmation one needs that nobody in the Git
> community cares much

On the contrary, we care a lot, but once you're not a new user
yourself anymore, it's hard to know what to fix.

> There probably is a radical case to be made for abandoning the word
> “tracking” entirely. First, because tracking branches don’t track, and
> second because “tracking” already means something else in Git (see
> below). I realise that this terminology is now so ingrained in Git
> users that conservatism will probably perpetuate it. But it would be
> *very* helpful to think this through, and at least agree on who
> “tracks” what. In the ideal world, origin/master would be something
> like “the fetching branch” for the origin’s master, or the “snapshot
> branch” or the “fetched branch”.
> [...]
> More radically, I am sure some head scratching would be able to find
> useful terminology for master, origin/master, and origin’s master. I’d
> love to see suggestions. As I said, I admire how wonderfully simple
> and clean this has been implemented, and the documentation, CLI, and
> terminology should reflect that.

I don't have any objections to changing these terms, but I don't have
any suggestions on what to change them _to_.

> 2. Introduce the alias `git unstage` for `git reset HEAD` in the
> standard distribution.

(or 'git rm --cached' for newly added files)

>    nothing added to commit but untracked files present
>
> should be
>
>    nothing staged to commit, but untracked files present

I've always liked the whole 'stage(d)' concept, so I like this, but I
remember Junio being fairly hesitant to use it more extensively.

> (Comment: maybe “... but working directory contains untracked files.”
> I realise that “directory” is not quite comprehensive here, because
> files can reside in subdirectories.

We use "worktree" elsewhere, how about that?

>    (use "git track <file>" to track)

So basically you want to split out 'git add' into 'git track' and 'git stage'?

>    Changes to be committed:
>    (use "git reset HEAD <file>..." to unstage)
>
> should be
>
>    Staged to be committed:
>    (use "git unstage <file>" to unstage)

This would be extra nice since 'git unstage' could also be used in a
fresh repository.


> But this is a good example of what’s wrong with the way the
> documentation thinks: Git’s implementation perspective should not
> define how concepts are explained. In particular, *tracking* (in the
> sense of making a file known to git) and *staging* are conceptually
> different things. In fact, the two things remain conceptually
> different later on: un-tracking (removing the file from Git’s
> worldview) and un-staging are not the same thing at all, neither
> conceptually nor implementationally.

Fair point, I think.

> The opposite of staging is `git
> reset HEAD <file>` and the opposite of tracking is -- well, I’m not
> sure, actually. Maybe `git update-index --force-remove <filename>`?

'git rm --cached'

> The entire quoted paragraph in the tutorial can be removed: there’s
> simply no reason to tell the reader that git behaves differently from
> other version control systems

I disagree, many people come from another VCS, and pointing out where
their assumptions are invalid is generally useful.

> There’s another issue with this, namely that “added files are
> immediately staged”. In fact, I do understand why Git does that, but
> conceptually it’s pure evil: one of the conceptual conrnerstones of
> Git -- that files can be tracked and changed yet not staged, i.e., the
> staging areas is conceptually a first-class citizen -- is violated
> every time a new file is “born”. Newborn files are *special* until
> their first commit, and that’s a shame, because the first thing the
> new file (and, vicariously, the new user) experiences is an
> aberration.

Eh, I think it's not an aberration, it's more of a convenience. I
don't think the benefit of making the concept of tracking vs. staging
clear to the user is worth the hassle of having to execute two things
to do one thing (staging a new file). You can also see it the other
way around, why are new files any different from other files? Why
shouldn't you be able to stage new files?

-- 
Cheers,

Sverre Rabbelier

Re: Git terminology: remote, add, track, stage, etc.

[Matthieu Moy]

Thore Husfeldt <thore.husfeldt@gmail.com> writes:

> Read it as the friendly, but
> somewhat exasparated suggestions of a newcomer. I’d love to help (in
> the form of submitting patches to the documentation or CLI responses),
> but I’d like to test the waters first.

(it's common practice here to test the water with RFC/PATCHes too)

> There are at least two uses of the word *tracking* in Git's
> terminology.

Actually, there's a third, known to be rather unfortunate.

For example, when you clone a repository, by default, you end up with

1) The master branch hosted remotely
2) origin/master, locally, but "remote-tracking"
3) master, your working branch.

When you do a "git pull" when sitting on local branch master, Git
knows it must :

a) fetch (i.e. download) from branch 1) into branch 2)
b) merge from branch 2) into branch 1)

Rule a) come from remote.<remotename>.fetch, and rule b) comes from
branch.master.merge in your .git/config.

Usually, we refer to tracking branch to mean rule a), but the "track"
in "git branch --track" means "setup git for rule b) above".

We already came up with a better wording, namely "upstream", and used
in in "git push --set-upstream". Probably a next step would be to
deprecate any other occurence of --track meaning the same thing (git
checkout --track seems to me to be a candidate, git branch has both
--track and --set-upstream). One difficulty is to do that with
backward compatibility in mind.

> 3. Duplicate various occurences of `cached` flags as `staged` (and
> change the documentation and man pages accordingly), so as to have,
> e.g., `git diff --staged`.

I do like this, but to be complete, one should also deal with more
complex cases. For example, "git apply" has _both_ --index and
--cached, with different semantics.

And changing just _some_ of the occurences of --index and --cached may
help, but do not fix the problem of inconsistancies. Up to now, there
have been many efforts towards consistancy, but I guess no one had the
courrage of doing a global-enough approach to eliminate all
inconsistancies.

In other words, I encourage you to continue the effort you've stated
here, but that won't help much unless you push the idea far enough
IMHO.

>     changed but not updated:
>
> I’m still not sure what “update” was ever supposed to mean in this
> sentence.

Historically, the staging area was seen as a cache (hence the name),
which was purposedly out-of-date when doing a partial commit. Hence,
Git inherited some of the terminology of usual caches (a cache is
"dirty" when it's not in sync with what it caches, "clean" when it is,
and you "update" it to make it in sync).

But I do agree that the analogy with a cache is disturbing for the
user, even if it's meaningful for the developper: as a user, a cache
is meant to be a performance optimization, not supposed to interfer
with the functionality.

> 2.
>     Untracked files:
>     (use "git add <file>..." to include in what will be committed)
>
> should be
>
>     Untracked files:
>     (use "git track <file>" to track)

This hypothetical "git track" actually exists under the name "git add
-N".

> The opposite of staging is `git
> reset HEAD <file>` and the opposite of tracking is -- well, I’m not
> sure, actually. Maybe `git update-index --force-remove <filename>`?

git rm --cached ?

As a bare mortal, you shouldn't need update-index, it's a plumbing
command (i.e. meant for scripts or low-level manipulations).

> An even more radical suggestion (which would take all of 20 seconds to
> implement) is to introduce `git track` as another alias for `git
> add`. (See above under `git status`). This would be especially useful
> if tracking *branches* no longer existed.

I disagree that adding aliases would help users. See your confusion,
and then the relief when you found out that index, cache, and staging
area were synonymous. Now, what should a user think after learning
stage, track and add, and asking for the difference.

I agree that adding new files and adding new content to existing files
are done for different reasons, but the conceptual simplicity of Git
comes from the fact that Git is purely snapshot oriented, and I to
some extent, it's nice to have this reflected in the user-interface.

When you say "git add X", you don't talk about the difference between
the previous commit and the next, or about the difference between
working tree and next commit, or so. You're basically saying "file X
will exist in the next commit, and it will have this content". Whether
it existed or not in the previous commit doesn't matter. It's
implemented this way, and it's really something fundamental in the Git
model.

> There’s another issue with this, namely that “added files are
> immediately staged”. In fact, I do understand why Git does that, but
> conceptually it’s pure evil: one of the conceptual conrnerstones of
> Git -- that files can be tracked and changed yet not staged,

Rephrase that as "the working tree can have content different from the
staged content". Both "working tree content" and "staged content" are
snapshot (i.e. they exist regardless of each other). Then newly
created files won't be different anymore. Files exist, with some
(possibly empty) content, or they don't.

-- 
Matthieu Moy
http://www-verimag.imag.fr/~moy/

Re: Git terminology: remote, add, track, stage, etc.

[Jakub Narebski]

Thore Husfeldt <thore.husfeldt@gmail.com> writes:

> I’ve just learned Git. What a wonderful system, thanks for building
> it. 
> 
> And what an annoying learning experience. 
> 
> I promised myself to try to remember what made it all so hard, and to
> write it down in a comprehensive and possibly even constructive
> fashion. Here it is, for what it’s worth. Read it as the friendly, but
> somewhat exasparated suggestions of a newcomer. I’d love to help (in
> the form of submitting patches to the documentation or CLI responses),
> but I’d like to test the waters first.

Thank you very much for writing those down.  It is very helpful for
us, which are used to Git and know by heart its sometimes obscure
jargon, and might not notice that it is hard to understand.
 

> Remote (tracking) branches
> --------------------------
> 
> There are at least two uses of the word *tracking* in Git's
> terminology.
> 
> The first, used in the form `git tracks a file' (in the sense that Git
> knows about the file) is harmless enough, and is handled under `git
> add` below.

In this sense of "tracked", i.e. "tracked file", it means that given
file is versioned / is under version control.

Though I don't think we use `git tracks a file` anywhere in the
documentation and messages (at least I hope so); we use `tracked file`.
I think it is all right for `tracked file` and `"tracked" branch`
to mean different things.


> But the real monster is the *tracking branch*, sometimes called the
> remote branch, the remote-tracking branch, or the remote tracking
> branch.  Boy did that ever confuse me. [...]
> 
> Please, *please* fix this. It was the single most confusing and
> annoying part of learning Git.
> 
> First, the word, "tracking". These branches don’t track or follow
> anything.  They are standing completely still.  Please believe me that
> when first you are led to believe that origin/master tracks a branch
> on the remote (like a hound tracks it quarry, or a radar tracks a
> flight) that it is very difficult to hunt this misunderstanding down:
> I believed for a long time that the tracking branch stayed in sync,
> automagically, with a synonymous branch at the remote.

But those 'remote-tracking branches' are *used* to track where there
are branches in remote repository.

Sidenote: give thanks that you didn't start to use git before version
1.5.0, when so called "separate remote" layout was made default (which
means tracking branch 'foo' in remote 'origin' using 'origin/foo'
remote-tracking branch).

[...]

> The hyphenated *remote-tracking* is a lot better terminology already
> (and sometimes even used in the documentation), because at least it
> doesn't pretend to be a remote branch (`git branch -r`, of course,
> still does). So that single hyphen already does some good, and should
> be edited for consistency. [...]

The name 'remote-tracking branch' is the name we arrived at after long
discussions not that long time ago, and it is a name that should be
used thorough the documentation.  It is ongoing effort.

> [...] It may be that terminology is slowly converging. (To something
> confusing, but still...)

[...]

> More radically, I am sure some head scratching would be able to find
> useful terminology for master, origin/master, and origin’s master. I’d
> love to see suggestions. As I said, I admire how wonderfully simple
> and clean this has been implemented, and the documentation, CLI, and
> terminology should reflect that.

There is also additional complication that you can have the same
relation that local branch 'master' has to 'origin/master'
remote-tracking branch with two local branches.

We nowadays say that 'origin/master' is "upstream" for 'master'
branch; we used to say that 'master' branch "tracks" 'origin/master'
branch (which can be seen in the name of `--track' option to 
'git branch').
 
> The staging area
> ----------------
> 
> The wonderful and central concept of staging area exists under at
> least three names in Git terminology. And that’s really, really
> annoying. The index, the cache, and the staging area are all the same,
> which is a huge revelation to a newcomer.

This inconsistence is results of historical issues; the concrete
object that is used as mediator betweeb working area and repository
was first called 'dircache', and now is called 'the index'.

There was strong push towards replacing 'index' and 'cache' by
'staging area' (and 'to stage' as verb), but it meets with some
resistance.


> 2. Introduce the alias `git unstage` for `git reset HEAD` in the
> standard distribution.

That is IMHO a very good idea.  The `git unstage <file>` form
describes what we want to achieve (user story), while `git reset HEAD
<file>` requires us to know what operation must we do in order to
remove staged changes from a file.
 
> 3. Duplicate various occurences of `cached` flags as `staged` (and
> change the documentation and man pages accordingly), so as to have,
> e.g., `git diff --staged`.

Note that it is not as easy as it seems at first glance.  There are
*two* such options, which (as you can read in gitcli(7) manpage) have
slightly different meaning:

 * The `--cached` option is used to ask a command that
   usually works on files in the working tree to *only* work
   with the index.  For example, `git grep`, when used
   without a commit to specify from which commit to look for
   strings in, usually works on files in the working tree,
   but with the `--cached` option, it looks for strings in
   the index.

 * The `--index` option is used to ask a command that
   usually works on files in the working tree to *also*
   affect the index.  For example, `git stash apply` usually
   merges changes recorded in a stash to the working tree,
   but with the `--index` option, it also merges changes to
   the index as well.

Some commands like `git apply` support both (though not at the same
time).


> git status
> ----------

[...]
> 2.
>     Untracked files:
>     (use "git add <file>..." to include in what will be committed)
> 
> should be
> 
>     Untracked files:
>     (use "git track <file>" to track)

To "track a file" means to put a file under version control (to
version control the file).

Note also that "git track <file>" would be "git add -N <file>" 
(where `-N` is `--intent-to-add`), which only marks a file to be
tracked / versioned, but doesn't stage its contents.
 
> Adding
> ------
> 
> The tutorial tells us that 
> 
>     Many revision control systems provide an add command that tells
>     the system to start tracking changes to a new file. Git's add
>     command does something simpler and more powerful: git add is used
>     both for new and newly modified files, and in both cases it takes
>     a snapshot of the given files and stages that content in the
>     index, ready for inclusion in the next commit.
> 
> This is true, and once you grok how Git actually works it also makes
> complete sense. `Making the file known to Git' (sometimes called
> `tracking the file') and `staging for the next commit' result in the
> exact same operations, from Git’s perspective.
> 
> But this is a good example of what’s wrong with the way the
> documentation thinks: Git’s implementation perspective should not
> define how concepts are explained. In particular, *tracking* (in the
> sense of making a file known to git) and *staging* are conceptually
> different things.

But they are not independent.  When you stage contents of a file which
was not known to git, it is automatically made "tracked" i.e. put
under version control.  Obvious.

>                    In fact, the two things remain conceptually
> different later on: un-tracking (removing the file from Git’s
> worldview) and un-staging are not the same thing at all, neither
> conceptually nor implementationally. The opposite of staging is `git
> reset HEAD <file>` and the opposite of tracking is -- well, I’m not
> sure, actually. Maybe `git update-index --force-remove <filename>`?

`git rm <filename>` to remove it both from staging area, and working
area, or `git rm --cached <filename>` to remove it only from staging
area, which means that it is removed from version control but kept on
disk.

[...]

> Fixing this requires no change to the implementation. `git stage` is
> already a synonym for `git add`. It merely requires discipline in
> using the terminology of staging. Note that it completely valid to
> tell the reader, maybe immediately and in a footnote, that `git add`
> and `git stage` *are* indeed synonyms, because of Git’s elegant
> model. In fact, given the amount of documentation cruft one can find
> on the Internet, this would be a welcome footnote.
> 
> An even more radical suggestion (which would take all of 20 seconds to
> implement) is to introduce `git track` as another alias for `git
> add`. (See above under `git status`). This would be especially useful
> if tracking *branches* no longer existed.

Well, there is different suggestion: make `git stage`, `git track` and
`git mark-resolved` to be *specializations* of `git add`, with added
safety checks: 'git stage' would work only on files known to git /
under version control already, 'git track' would work only on
untracked files (and do what 'git add -N' does), and 'git mark-resolved'
would work only on files which were part of a merge conflict.
 
> There’s another issue with this, namely that “added files are
> immediately staged”. In fact, I do understand why Git does that, but
> conceptually it’s pure evil: one of the conceptual conrnerstones of
> Git -- that files can be tracked and changed yet not staged, i.e., the
> staging areas is conceptually a first-class citizen -- is violated
> every time a new file is “born”. Newborn files are *special* until
> their first commit, and that’s a shame, because the first thing the
> new file (and, vicariously, the new user) experiences is an
> aberration. I admit that I have not thought this through.

-- 
Jakub Narebski
Poland
ShadeHawk on #git

[RFC/PATCH] reset: accept "git reset <removed file>"

[Jonathan Nieder]

Suppose I try to use "git reset" to un-add an new, unwanted file:

	echo hello >foo.c
	git add foo.c
	rm foo.c; # bad file! bad!
	git reset foo.c

The file foo.c does not exist on disk, so "git reset" rejects the
request with

	fatal: ambiguous argument 'foo.c': unknown revision or path not in the working tree.
	Use '--' to separate paths from revisions

Git can do better: since foo.c is not a revision and has an entry in
the index, it is clear the request refers to a path and not a rev.

Signed-off-by: Jonathan Nieder <jrnieder@gmail.com>
---
Jonathan Nieder wrote:

> Ah, this is a kind of obnoxious thing!  For a newly added file,
>
> 	git reset -- <path>
>
> ought to un-add it, but it doesn't.

Err, yes it does.  Probably I was thinking of

	rm <path>
	git reset <path>

producing an "ambiguous argument" message.

 builtin/reset.c  |    8 +++++++-
 t/t7102-reset.sh |   34 ++++++++++++++++++++++++++++++++--
 2 files changed, 39 insertions(+), 3 deletions(-)

diff --git a/builtin/reset.c b/builtin/reset.c
index 0037be4..7d23d75 100644
--- a/builtin/reset.c
+++ b/builtin/reset.c
@@ -295,7 +295,13 @@ int cmd_reset(int argc, const char **argv, const char *prefix)
 			rev = argv[i++];
 		} else {
 			/* Otherwise we treat this as a filename */
-			verify_filename(prefix, argv[i]);
+			const char *name = argv[i];
+			if (prefix)
+				name = prefix_filename(prefix, strlen(prefix), name);
+			if (read_cache() < 0)
+				die("Could not read index");
+			if (cache_name_pos(name, strlen(name)) < 0)
+				verify_filename(prefix, argv[i]);
 		}
 	}
 
diff --git a/t/t7102-reset.sh b/t/t7102-reset.sh
index b8cf260..69d125e 100755
--- a/t/t7102-reset.sh
+++ b/t/t7102-reset.sh
@@ -5,7 +5,7 @@
 
 test_description='git reset
 
-Documented tests for git reset'
+Miscellaneous tests for git reset'
 
 . ./test-lib.sh
 
@@ -441,6 +441,15 @@ test_expect_success 'disambiguation (1)' '
 
 '
 
+test_expect_success "disambiguation (1')" '
+
+	git reset --hard &&
+	git reset secondfile &&
+	git diff --exit-code &&
+	git diff --cached --exit-code
+
+'
+
 test_expect_success 'disambiguation (2)' '
 
 	git reset --hard &&
@@ -448,11 +457,18 @@ test_expect_success 'disambiguation (2)' '
 	git add secondfile &&
 	rm -f secondfile &&
 	test_must_fail git reset secondfile &&
-	test -n "$(git diff --cached --name-only -- secondfile)" &&
+	test -z "$(git diff --cached --name-only)" &&
 	test ! -f secondfile
 
 '
 
+test_expect_success "disambiguation (2')" '
+
+	git reset --hard &&
+	test_must_fail git reset doesnotexist
+
+'
+
 test_expect_success 'disambiguation (3)' '
 
 	git reset --hard &&
@@ -465,6 +481,13 @@ test_expect_success 'disambiguation (3)' '
 
 '
 
+test_expect_success "disambiguation (3')" '
+
+	git reset --hard &&
+	git reset HEAD doesnotexist
+
+'
+
 test_expect_success 'disambiguation (4)' '
 
 	git reset --hard &&
@@ -476,4 +499,11 @@ test_expect_success 'disambiguation (4)' '
 	test ! -f secondfile
 '
 
+test_expect_success "disambiguation (4')" '
+
+	git reset --hard &&
+	git reset -- doesnotexist
+
+'
+
 test_done
-- 
1.7.2.3

Re: [RFC/PATCH] reset: accept "git reset <removed file>"

[Junio C Hamano]

Jonathan Nieder <jrnieder@gmail.com> writes:

> Suppose I try to use "git reset" to un-add an new, unwanted file:
>
> 	echo hello >foo.c
> 	git add foo.c
> 	rm foo.c; # bad file! bad!
> 	git reset foo.c
>
> The file foo.c does not exist on disk, so "git reset" rejects the
> request with
>
> 	fatal: ambiguous argument 'foo.c': unknown revision or path not in the working tree.
> 	Use '--' to separate paths from revisions
>
> Git can do better: since foo.c is not a revision and has an entry in
> the index, it is clear the request refers to a path and not a rev.
>
> Signed-off-by: Jonathan Nieder <jrnieder@gmail.com>
> ---

This changes the definition of path/rev disambiguation only for "reset"
and makes things inconsistent.  Is it a good thing?

If a token is not a filename in the working tree, but is a path in the
index, and at the same time is a valid ref, wouldn't it make the token
ambiguous with the updated definition of disambiguation code here?

> diff --git a/builtin/reset.c b/builtin/reset.c
> index 0037be4..7d23d75 100644
> --- a/builtin/reset.c
> +++ b/builtin/reset.c
> @@ -295,7 +295,13 @@ int cmd_reset(int argc, const char **argv, const char *prefix)
>  			rev = argv[i++];
>  		} else {
>  			/* Otherwise we treat this as a filename */
> -			verify_filename(prefix, argv[i]);
> +			const char *name = argv[i];
> +			if (prefix)
> +				name = prefix_filename(prefix, strlen(prefix), name);
> +			if (read_cache() < 0)
> +				die("Could not read index");
> +			if (cache_name_pos(name, strlen(name)) < 0)
> +				verify_filename(prefix, argv[i]);
>  		}
>  	}

Makes me wonder

 - if we can/want to have a logic like this inside verify_filename();

 - if we need a corresponding logic in either the previous else/if cascade
   that calls verify_non_filename(), or in verify_non_filename() itself.

Re: Git terminology: remote, add, track, stage, etc.

[Junio C Hamano]

Sverre Rabbelier <srabbelier@gmail.com> writes:

>> More radically, I am sure some head scratching would be able to find
>> useful terminology for master, origin/master, and origin’s master. I’d
>> love to see suggestions. As I said, I admire how wonderfully simple
>> and clean this has been implemented, and the documentation, CLI, and
>> terminology should reflect that.
>
> I don't have any objections to changing these terms, but I don't have
> any suggestions on what to change them _to_.

I do not think debating on changing the terminology is a particularly
productive use of our time.  Just like Thore was confused by "index,
cache, add, stage", we would end up adding yet another lingo that cover
the same concept, and the problem is that there is _no way_ older words
will be forgotten.

But I think the way the concepts are explained and taught by our
documentation can and should be improved.  For example, as I've written
before we use 'tracking' for two quite different purposes, which is a
mistake and the source confusion.

 - A "remote-tracking branch" is "a _thing_ whose purpose is to be used to
   track a branch on the remote side", and "fetch" is how you update it.

 - Sometimes people call a local branch whose purpose is to be used to
   build on efforts made on a branch on a remote repository as "tracking",
   which is quite incompatible with the above one.

Re: [RFC/PATCH] reset: accept "git reset <removed file>"

[Jonathan Nieder]

Junio C Hamano wrote:

> Makes me wonder
>
>  - if we can/want to have a logic like this inside verify_filename();

Yes, I think so.  I was worried that this would be confusing for some
command that looks to the worktree, like git grep without --cached,
but I suspect that worry was unfounded.

The one case I am worried about is "git rev-parse".  What is
"git rev-parse <path>" supposed to be used for?

>  - if we need a corresponding logic in either the previous else/if cascade
>    that calls verify_non_filename(), or in verify_non_filename() itself.

Yes.

Is it safe to load the index so early?  I can imagine a person trying
"git reset" to recover from a corrupted index; are we regressing in
that respect and how would one check for it?

Re: Git terminology: remote, add, track, stage, etc.

[Miles Bader]

Matthieu Moy <Matthieu.Moy@grenoble-inp.fr> writes:
> We already came up with a better wording, namely "upstream", and used
> in in "git push --set-upstream".  Probably a next step would be to
> deprecate any other occurence of --track meaning the same thing

That doesn't make much sense to me; "upstream" and "track" are not
alternatives; rather, they're complementary:  "upstream" is a _thing_,
and "track" is an _action_ -- one _tracks_ _upstream_.  "--track", then,
merely implies "upstream", which seems fine to me, as I'm not sure
there's anything else it could refer to.

I think the original post, while well-meaning is a bit overwrought, and
reflects the difficulty in learning any new system as much as it does
any inconsistency in git's terminology[*] -- Git's huge sin, after all
(judging from most complaints I see about it), is that It Doesn't Use
Exactly The Same Model (and thus Terminology) That CVS Did...

[SVN's great sin, of course, is that It Does (interpret "CVS" liberally
here).]

[*] Git is certainly guilty of using inconsistent terminology --
cached/staged/index/yada is my personal complaint -- but I don't think
to anywhere near the degree implied by that post.

-Miles

-- 
Do not taunt Happy Fun Ball.

Re: Git terminology: remote, add, track, stage, etc.

[Wincent Colaiuta]

El 19/10/2010, a las 06:49, Miles Bader escribió:

> I think the original post, while well-meaning is a bit overwrought, and
> reflects the difficulty in learning any new system as much as it does
> any inconsistency in git's terminology[*] -- Git's huge sin, after all
> (judging from most complaints I see about it), is that It Doesn't Use
> Exactly The Same Model (and thus Terminology) That CVS Did...

I don't think it's overwrought at all. It's just pointing out a couple of obvious road-bumps in the learning curve.

We should smooth out these road-bumps (in so far as we can, with respect to backward compatibility and such) rather than just hand-waving them away saying that they are a natural consequence of demolishing the CVS world view and replacing it with something better. That's not true at all; mistakes _were_ made with the terminology, and unfortunately we have to live with some of them because they can't be changed in a non-breaking way, but the changes that we _can_ make to remove the confusion, we should make them.

Cheers,
Wincent

Re: Git terminology: remote, add, track, stage, etc.

[Miles Bader]

On Tue, Oct 19, 2010 at 4:19 PM, Wincent Colaiuta <win@wincent.com> wrote:
> We should smooth out these road-bumps (in so far as we can, with respect to backward compatibility and such) rather than just hand-waving them away saying that they are a natural consequence of demolishing the CVS world view and replacing it with something better. That's not true at all; mistakes _were_ made with the terminology, and unfortunately we have to live with some of them because they can't be changed in a non-breaking way, but the changes that we _can_ make to remove the confusion, we should make them.

Sure, I'm not claiming that git's perfect or can't be improved.  [As I
noted, I have my own list of complaints about its terminology.]

However, just as it's wrong to ignore all complaints for such reasons,
it's _equally_ wrong to assume the opposite and think that all such
complaints are justified.  Some differences in terminology _are_ due
to a very different model, and can't simply be papered over.  It isn't
"hand-waving" to point this out.  They might (and should) be better
documented/explained, but there are definitely terms and concepts
where the only reasonable solution is for newbies to have some
patience and take some time to learn them.

My impression of the original post was that it contained a little of both.

-Miles

-- 
Cat is power.  Cat is peace.

Re: Git terminology: remote, add, track, stage, etc.

[Wincent Colaiuta]

El 19/10/2010, a las 09:48, Miles Bader escribió:

> On Tue, Oct 19, 2010 at 4:19 PM, Wincent Colaiuta <win@wincent.com> wrote:
>> We should smooth out these road-bumps (in so far as we can, with respect to backward compatibility and such) rather than just hand-waving them away saying that they are a natural consequence of demolishing the CVS world view and replacing it with something better. That's not true at all; mistakes _were_ made with the terminology, and unfortunately we have to live with some of them because they can't be changed in a non-breaking way, but the changes that we _can_ make to remove the confusion, we should make them.
> 
> Sure, I'm not claiming that git's perfect or can't be improved.  [As I
> noted, I have my own list of complaints about its terminology.]
> 
> However, just as it's wrong to ignore all complaints for such reasons,
> it's _equally_ wrong to assume the opposite and think that all such
> complaints are justified.  Some differences in terminology _are_ due
> to a very different model, and can't simply be papered over.  It isn't
> "hand-waving" to point this out.  They might (and should) be better
> documented/explained, but there are definitely terms and concepts
> where the only reasonable solution is for newbies to have some
> patience and take some time to learn them.

Well, I'm not "assuming" that the complaints are justified; I'm talking from 3.5 years of personal experience using Git:

- the concept of the "index": learnt it in 30 seconds, and sick of hearing people complain about it

- terminology related to concepts of "tracking"/"remote(s)": discomfort almost every time I've had to deal with it

gitglossary(7) helps, but no matter how good it is you'll still get confusion unless the terminology is used consistently across the board. Some of this is not actually Git's fault, as a lot of the misuse/abuse of terminology actually comes from people writing blog posts and presentations and not being disciplined about their use of language -- before you know it Google returns mostly garbage results and "the community" ends up speaking a corrupted version of the language --  but the stuff that is within the scope of the Git project itself (man pages, official docs, interfaces) really needs to be top notch.

Cheers,
Wincent

Re: Git terminology: remote, add, track, stage, etc.

[Matthijs Kooijman]

[-- Attachment #1: Type: text/plain, Size: 1554 bytes --]

>  * The `--cached` option is used to ask a command that
>    usually works on files in the working tree to *only* work
>    with the index.  For example, `git grep`, when used
>    without a commit to specify from which commit to look for
>    strings in, usually works on files in the working tree,
>    but with the `--cached` option, it looks for strings in
>    the index.
> 
>  * The `--index` option is used to ask a command that
>    usually works on files in the working tree to *also*
>    affect the index.  For example, `git stash apply` usually
>    merges changes recorded in a stash to the working tree,
>    but with the `--index` option, it also merges changes to
>    the index as well.

Doesn't this just offer opportunity for two new options? E.g., --staged
and --also-staged or --include-staged or something? In the current form,
these two options provide a variation of the same concept, using
completely different option names (which could lead people to think
that they're really the same option, just inconsistently implemented).

So, regardless of changing over to --staged, I guess these two options
could be made more consistent (though sticking to the "index"
terminology is tricky, since that would require --cached to be become
--index and --index to become --include--index, which throws away
backward compatibility...).

FWIW, I do rather like the "staging area" concept, since I feel it
accurately describes its use (or at least the most common use of the
staging area).

Gr.

Matthijs

[-- Attachment #2: Digital signature --]
[-- Type: application/pgp-signature, Size: 197 bytes --]

Re: Git terminology: remote, add, track, stage, etc.

[Jakub Narebski]

On Tue, 19 Oct 2010, Matthijs Kooijman wrote:

Note that the excerpt cited (quoted) below is directly from gitcli(7)
manpage.

> >  * The `--cached` option is used to ask a command that
> >    usually works on files in the working tree to *only* work
> >    with the index.  For example, `git grep`, when used
> >    without a commit to specify from which commit to look for
> >    strings in, usually works on files in the working tree,
> >    but with the `--cached` option, it looks for strings in
> >    the index.

Mnemonic: operate on _cached_ contents.  We could use `--staged`
instead of `--cached` here, but for me it doesn't as strong as
`--cached` this meaning.

> > 
> >  * The `--index` option is used to ask a command that
> >    usually works on files in the working tree to *also*
> >    affect the index.  For example, `git stash apply` usually
> >    merges changes recorded in a stash to the working tree,
> >    but with the `--index` option, it also merges changes to
> >    the index as well.

Mnemonic: include _index_ (the name for concrete implementation of the
staging area) in operation.  We could use `--stage` here, but it would
be confusingly similar to `--staged`.  We could use `--include-staged`
or `--also-staged`, but it is long and unwieldy, and doesn't read as
nice.

> 
> Doesn't this just offer opportunity for two new options? E.g., --staged
> and --also-staged or --include-staged or something? In the current form,
> these two options provide a variation of the same concept, using
> completely different option names (which could lead people to think
> that they're really the same option, just inconsistently implemented).

That's why documentation is for.  That is why we have gitcli(7).

Sidenote: there were some proposal of including pseudo-ref name for
cache/index/staging area (and for workdir contents), i.e. to use for
example INDEX or STAGE instead of `--cached`... but they fell flat
because `--cached` / STAGE is not exactly like the ref, and it felt
like it would contribute to confusion rather than reducing it.

> 
> So, regardless of changing over to --staged, I guess these two options
> could be made more consistent (though sticking to the "index"
> terminology is tricky, since that would require --cached to be become
> --index and --index to become --include-index, which throws away
> backward compatibility...).

Breaking backward compatibility that badly is a big NO.

Unfortunately the need for backward compatibility prevents us from some
of improvements...

> 
> FWIW, I do rather like the "staging area" concept, since I feel it
> accurately describes its use (or at least the most common use of the
> staging area).

I also like "staging area" concept (and "to stage" as a verb), but there
are some difficulties in applying it thorough and through.

-- 
Jakub Narebski
Poland

[PATCH v3] Porcelain scripts: Rewrite cryptic "needs update" error message

[Ramkumar Ramachandra]

Although Git interally has the facility to differentiate between
porcelain and plubmbing commands and appropriately print errors,
several shell scripts invoke plubming commands triggering cryptic
plumbing errors to be displayed on a porcelain interface. This patch
replaces the "needs update" message in git-pull and git-rebase, when
`git update-index` is run, with a more friendly message.

Reported-by: Joshua Jensen <jjensen@workspacewhiz.com>
Reported-by: Thore Husfeldt <thore.husfeldt@gmail.com>
Signed-off-by: Ramkumar Ramachandra <artagnon@gmail.com>
---
 Ref: <1285877017-8060-1-git-send-email-artagnon@gmail.com> for v2.
 Ref: <1285514516-5112-1-git-send-email-artagnon@gmail.com> for v1.

 Thanks to Matthieu for reviewing v1 and Junio for reviewing v2: I've
 tried to attack the problem more conservatively in this patch. It
 doesn't list paths, and doesn't print "generic" advice.

 git-pull.sh                |    5 +----
 git-rebase--interactive.sh |   14 +++-----------
 git-rebase.sh              |   14 +-------------
 git-sh-setup.sh            |   29 +++++++++++++++++++++++++++++
 4 files changed, 34 insertions(+), 28 deletions(-)

diff --git a/git-pull.sh b/git-pull.sh
index 8eb74d4..20a3bbe 100755
--- a/git-pull.sh
+++ b/git-pull.sh
@@ -201,10 +201,7 @@ test true = "$rebase" && {
 			die "updating an unborn branch with changes added to the index"
 		fi
 	else
-		git update-index --ignore-submodules --refresh &&
-		git diff-files --ignore-submodules --quiet &&
-		git diff-index --ignore-submodules --cached --quiet HEAD -- ||
-		die "refusing to pull with rebase: your working tree is not up-to-date"
+		require_clean_work_tree "pull with rebase" "Please commit or stash them."
 	fi
 	oldremoteref= &&
 	. git-parse-remote &&
diff --git a/git-rebase--interactive.sh b/git-rebase--interactive.sh
index a27952d..4d8a2a0 100755
--- a/git-rebase--interactive.sh
+++ b/git-rebase--interactive.sh
@@ -153,14 +153,6 @@ run_pre_rebase_hook () {
 	fi
 }
 
-require_clean_work_tree () {
-	# test if working tree is dirty
-	git rev-parse --verify HEAD > /dev/null &&
-	git update-index --ignore-submodules --refresh &&
-	git diff-files --quiet --ignore-submodules &&
-	git diff-index --cached --quiet HEAD --ignore-submodules -- ||
-	die "Working tree is dirty"
-}
 
 ORIG_REFLOG_ACTION="$GIT_REFLOG_ACTION"
 
@@ -557,7 +549,7 @@ do_next () {
 			exit "$status"
 		fi
 		# Run in subshell because require_clean_work_tree can die.
-		if ! (require_clean_work_tree)
+		if ! (require_clean_work_tree "rebase")
 		then
 			warn "Commit or stash your changes, and then run"
 			warn
@@ -768,7 +760,7 @@ first and then run 'git rebase --continue' again."
 
 		record_in_rewritten "$(cat "$DOTEST"/stopped-sha)"
 
-		require_clean_work_tree
+		require_clean_work_tree "rebase"
 		do_rest
 		;;
 	--abort)
@@ -866,7 +858,7 @@ first and then run 'git rebase --continue' again."
 
 		comment_for_reflog start
 
-		require_clean_work_tree
+		require_clean_work_tree "rebase" "Please commit or stash them."
 
 		if test ! -z "$1"
 		then
diff --git a/git-rebase.sh b/git-rebase.sh
index e5df23b..988b3d8 100755
--- a/git-rebase.sh
+++ b/git-rebase.sh
@@ -416,19 +416,7 @@ else
 	fi
 fi
 
-# The tree must be really really clean.
-if ! git update-index --ignore-submodules --refresh > /dev/null; then
-	echo >&2 "cannot rebase: you have unstaged changes"
-	git diff-files --name-status -r --ignore-submodules -- >&2
-	exit 1
-fi
-diff=$(git diff-index --cached --name-status -r --ignore-submodules HEAD --)
-case "$diff" in
-?*)	echo >&2 "cannot rebase: your index contains uncommitted changes"
-	echo >&2 "$diff"
-	exit 1
-	;;
-esac
+require_clean_work_tree "rebase" "Please commit or stash them."
 
 if test -z "$rebase_root"
 then
diff --git a/git-sh-setup.sh b/git-sh-setup.sh
index ae031a1..aa16b83 100644
--- a/git-sh-setup.sh
+++ b/git-sh-setup.sh
@@ -145,6 +145,35 @@ require_work_tree () {
 	die "fatal: $0 cannot be used without a working tree."
 }
 
+require_clean_work_tree () {
+	git rev-parse --verify HEAD >/dev/null || exit 1
+	git update-index -q --ignore-submodules --refresh
+	err=0
+
+	if ! git diff-files --quiet --ignore-submodules
+	then
+		echo >&2 "Cannot $1: You have unstaged changes."
+		err=1
+	fi
+
+	if ! git diff-index --cached --quiet --ignore-submodules HEAD --
+	then
+		if [ $err = 0 ]
+		then
+		    echo >&2 "Cannot $1: Your index contains uncommitted changes."
+		else
+		    echo >&2 "Additionally, your index contains uncommitted changes."
+		fi
+		err=1
+	fi
+
+	if [ $err = 1 ]
+	then
+		test -n "$2" && echo >&2 "$2"
+		exit 1
+	fi
+}
+
 get_author_ident_from_commit () {
 	pick_author_script='
 	/^author /{
-- 
1.7.2.2.409.gdbb11.dirty

Re: Git terminology: remote, add, track, stage, etc.

[Eugene Sajine]

> Well, I'm not "assuming" that the complaints are justified; I'm talking from 3.5 years of personal experience using Git:
>
> - the concept of the "index": learnt it in 30 seconds, and sick of hearing people complain about it
>
> - terminology related to concepts of "tracking"/"remote(s)": discomfort almost every time I've had to deal with it
>

I concur. I 'm working with a couple of dozen of people and helping
them to learn git and the most confusing part is the tracking/remote
because of too many meanings of the same words in use.

We are talking about the tracking branch which is "local remote", but
we also can create a tracking branch that will track the remote but
will be local like:
$git branch -t dev origin/dev

There should be some different consistent and not inter-crossing
naming for the origin's master branch (on the remote side), for the
local origin/master
and for local master that is a tracking branch. The only way i found
so far to explain this is actually via the naming syntax where having
/ in the name of the branch means remote branch. I was a bit surprised
that i can create a local branch with a slash in the name - probably
it should be prohibited.

In this light pull command not updating the remote ref, but FETCH_HEAD
is only adding to the overall confusion (I remember: it is pending
change)

Thanks,
Eugene

Re: Git terminology: remote, add, track, stage, etc.

[Thore Husfeldt]

Thank you all for your many and well-thought out replies. I learned a lot.

Jonathan Nieder:

> So what would be a better term [for tracking]?

Trailing is better than tracking, since it hints at some degree of sloth, but I have not thought this through. (I also think that it may be a strategic mistake to advocate looking for a new name; as long as tracking is used consistently the problem with a misleading metaphor is not so big, and the name change alienates a large group of people whose consent is important.)

> How will a person used to e.g. cvs ever adjust if they don't even realize git is different?

This comment, and similar from others, makes it clear that I made a mistake in taking up staging versus tracking. It sends a wrong signal about my intentions, and is only a minor detail. This was *not* so difficult to understand, so I shouldn’t have included it. My annoyance here is merely aesthetic and pedagogical.

Matthiey Moy:

> Git's huge sin, after all (judging from most complaints I see about it), is that It Doesn't Use Exactly The Same Model (and thus Terminology) That CVS Did...


My analysis of Git’s wickedness is interestingly different. Git has a clean and simple model that should be very easy to understand. Git’s rhetorical traditions prevent that understanding. Git is really, really hard to learn, no matter where you come from, but there is no inherent reason for that.

The steepness of the learning curve (rather than the divergence from other systems’s terminology) is the single biggest complaint against git, evidenced by my own anecdotal evidence from web surfing, and by the Git user survey. It should be viewed as Git’s biggest current problem by an order of magnitude. It makes me think twice and thrice before asking my colleagues to collaborate with me using Git; I will probably learn Mercurial and advocate using that instead—it’s almost as nice, and I don’t feel embarrassed advocating it. Using git for myself is great (now I understand it) but it is unclear if I should invest social capital to convince others to use it as well. 

The magnitude of how bad this is, and the urgency with which this should be fixed, is clear to everybody—except, naturally, the denizens of this mailing list. Not out of malice or incompetence, but *because of* familiarity.

Sverre Rabbelier:


> What do you mean with the last part (about `git branch -r`)? The fact
> that 'refs/remotes' is not immutable?

Well, consider for example the simple obfuscatory mastery of the following line in the user manual:

> $ git branch -r			# list all remote branches


Yes, I get it *now*. And I begin to feel the corruption spreading in my own brain already: I myself start to think of origin/master as a “remote branch”. Give me a few more weeks and I will be completely assimilated in the mindset.

(Note to self: submit a patch about this before my assimilation is complete. I already fixed it and committed to my local branch.)

Mattiey again:

> We already came up with a better wording, namely "upstream", and used in in "git push --set-upstream". 

Oh, I didn’t know that. I was convinced that “upstream” was cruft from when git was chiefly a tool to help Linus maintain the Linux kernel. Let‘s see if I get this right:

The remote-tracking branch “origin/master” is *upstream* (the upstream?) of the local branch “master”, and *tracks* the remote origin’s branch “master”? (local) “master” is downstream of “origin/master”?

This would be useful. And @{u} is good. (Does it have an inverse?)

I’m not sure I like the particular word, but that’s a minor complaint. 

( For completeness: A small terminological quibble is that upstream doesn’t verb well. A bigger conceptual quibble is that this decision is not workflow-neutral. It enforces git’s hierarchical linux-kernel development  tradition, rather than embracing a truly distributed model where everybody is the same. When I think of distributed version control I like to think of Alice having a remote-tracking bob/master and Bob having a remote-tracking alice/master. Of course, it is still meaningful for Alice to say “the upstream of bobs_latest_crazy_ideas is bob/master”, and for Bob to say “the upstream of alices_inane_ramblings is alice/master”. But it introduces a notion of hierarchy that is inimical to the concept of distribution, and not workflow-neutral. )

Of course, upstream could be called supercalifragilistic and I would still like it. Consistency is more important than having good metaphors. (But good metaphors would be better, all other things being equal.)

Jakup Narebski:

> Note that it is not as easy as it seems at first glance.  There are *two* such options, which (as you can read in gitcli(7) manpage) have slightly different meaning:

Wow. Thanks for pointing this out, I did not know that, and it explains a lot. I must say that to everybody else than a git developer, this state of affairs is a proof that something is wrong, rather than an obstruction for improvement.

>  I do not think debating on changing the terminology is a particularly productive use of our time.  

I agree in the sense that *how* the words are used is more important than *which* words are used, and I realise that I should not have put “terminology” in the headline, because that makes it about words, not *explanations* or terminological *discipline*. 

Re: [RFC/PATCH] reset: accept "git reset <removed file>"

[Junio C Hamano]

Jonathan Nieder <jrnieder@gmail.com> writes:

> Junio C Hamano wrote:
>
>> Makes me wonder
>>
>>  - if we can/want to have a logic like this inside verify_filename();
>
> Yes, I think so.  I was worried that this would be confusing for some
> command that looks to the worktree, like git grep without --cached,
> but I suspect that worry was unfounded.
>
> The one case I am worried about is "git rev-parse".  What is
> "git rev-parse <path>" supposed to be used for?
>
>>  - if we need a corresponding logic in either the previous else/if cascade
>>    that calls verify_non_filename(), or in verify_non_filename() itself.
>
> Yes.
>
> Is it safe to load the index so early?  I can imagine a person trying
> "git reset" to recover from a corrupted index; are we regressing in
> that respect and how would one check for it?

It is generally unsafe, I am afraid, and that is one of the reasons why
verify_filename() does not look in the index (the other one was "it is
merely a safety measure based on heuristics to help users, and no point
spending extra code nor cycles", iow, deliberate laziness ;-)), making the
proposal of this patch under discussion somewhat iffy.

Re: Git terminology: remote, add, track, stage, etc.

[Ramkumar Ramachandra]

Sverre Rabbelier writes:
> On Mon, Oct 18, 2010 at 15:45, Thore Husfeldt <thore.husfeldt@gmail.com> wrote:
> > The hyphenated *remote-tracking* is a lot better terminology already
> > (and sometimes even used in the documentation), because at least it
> > doesn't pretend to be a remote branch (`git branch -r`, of course,
> > still does).
> 
> What do you mean with the last part (about `git branch -r`)? The fact
> that 'refs/remotes' is not immutable?
> 
> > So that single hyphen already does some good, and should
> > be edited for consistency.
> 
> If we agree that "remote-tracking" is the way to go, a patch doing
> such editing would be very welcome.

-- 8< --
From a863e58d240956191c2fa9cbe992aaca5786730b Mon Sep 17 00:00:00 2001
From: Ramkumar Ramachandra <artagnon@gmail.com>
Date: Tue, 19 Oct 2010 22:42:05 +0530
Subject: [PATCH] Documentation: Consistently use the hyphenated "remote-tracking"

Replace instances of the term "remote tracking" with "remote-tracking"
in the documentation for clarity.

Reported-by: Thore Husfeldt <thore.husfeldt@gmail.com>
Signed-off-by: Ramkumar Ramachandra <artagnon@gmail.com>
---
 Documentation/config.txt           |    2 +-
 Documentation/fetch-options.txt    |    2 +-
 Documentation/git-gc.txt           |    2 +-
 Documentation/git-log.txt          |    2 +-
 Documentation/git-pull.txt         |    2 +-
 Documentation/git-remote.txt       |    4 ++--
 Documentation/gittutorial.txt      |    6 +++---
 Documentation/rev-list-options.txt |    2 +-
 Documentation/user-manual.txt      |    2 +-
 9 files changed, 12 insertions(+), 12 deletions(-)

diff --git a/Documentation/config.txt b/Documentation/config.txt
index 71ddb6c..736b22f 100644
--- a/Documentation/config.txt
+++ b/Documentation/config.txt
@@ -708,7 +708,7 @@ color.diff.<slot>::
 color.decorate.<slot>::
 	Use customized color for 'git log --decorate' output.  `<slot>` is one
 	of `branch`, `remoteBranch`, `tag`, `stash` or `HEAD` for local
-	branches, remote tracking branches, tags, stash and HEAD, respectively.
+	branches, remote-tracking branches, tags, stash and HEAD, respectively.
 
 color.grep::
 	When set to `always`, always highlight matches.  When `false` (or
diff --git a/Documentation/fetch-options.txt b/Documentation/fetch-options.txt
index 470ac31..a435c23 100644
--- a/Documentation/fetch-options.txt
+++ b/Documentation/fetch-options.txt
@@ -36,7 +36,7 @@ ifndef::git-pull[]
 
 -p::
 --prune::
-	After fetching, remove any remote tracking branches which
+	After fetching, remove any remote-tracking branches which
 	no longer exist	on the remote.
 endif::git-pull[]
 
diff --git a/Documentation/git-gc.txt b/Documentation/git-gc.txt
index 315f07e..d6d6833 100644
--- a/Documentation/git-gc.txt
+++ b/Documentation/git-gc.txt
@@ -89,7 +89,7 @@ are not part of the current project most users will want to expire
 them sooner.  This option defaults to '30 days'.
 
 The above two configuration variables can be given to a pattern.  For
-example, this sets non-default expiry values only to remote tracking
+example, this sets non-default expiry values only to remote-tracking
 branches:
 
 ------------
diff --git a/Documentation/git-log.txt b/Documentation/git-log.txt
index 6d40f00..ff41784 100644
--- a/Documentation/git-log.txt
+++ b/Documentation/git-log.txt
@@ -116,7 +116,7 @@ git log --follow builtin-rev-list.c::
 git log --branches --not --remotes=origin::
 
 	Shows all commits that are in any of local branches but not in
-	any of remote tracking branches for 'origin' (what you have that
+	any of remote-tracking branches for 'origin' (what you have that
 	origin doesn't).
 
 git log master --not --remotes=*/master::
diff --git a/Documentation/git-pull.txt b/Documentation/git-pull.txt
index c50f7dc..33e8438 100644
--- a/Documentation/git-pull.txt
+++ b/Documentation/git-pull.txt
@@ -26,7 +26,7 @@ With `--rebase`, it runs 'git rebase' instead of 'git merge'.
 <repository> should be the name of a remote repository as
 passed to linkgit:git-fetch[1].  <refspec> can name an
 arbitrary remote ref (for example, the name of a tag) or even
-a collection of refs with corresponding remote tracking branches
+a collection of refs with corresponding remote-tracking branches
 (e.g., refs/heads/*:refs/remotes/origin/*), but usually it is
 the name of a branch in the remote repository.
 
diff --git a/Documentation/git-remote.txt b/Documentation/git-remote.txt
index aa021b0..3143c89 100644
--- a/Documentation/git-remote.txt
+++ b/Documentation/git-remote.txt
@@ -75,7 +75,7 @@ was passed.
 
 'rename'::
 
-Rename the remote named <old> to <new>. All remote tracking branches and
+Rename the remote named <old> to <new>. All remote-tracking branches and
 configuration settings for the remote are updated.
 +
 In case <old> and <new> are the same, and <old> is a file under
@@ -84,7 +84,7 @@ the configuration file format.
 
 'rm'::
 
-Remove the remote named <name>. All remote tracking branches and
+Remove the remote named <name>. All remote-tracking branches and
 configuration settings for the remote are removed.
 
 'set-head'::
diff --git a/Documentation/gittutorial.txt b/Documentation/gittutorial.txt
index 1c16066..0982f74 100644
--- a/Documentation/gittutorial.txt
+++ b/Documentation/gittutorial.txt
@@ -385,7 +385,7 @@ alice$ git fetch bob
 
 Unlike the longhand form, when Alice fetches from Bob using a
 remote repository shorthand set up with 'git remote', what was
-fetched is stored in a remote tracking branch, in this case
+fetched is stored in a remote-tracking branch, in this case
 `bob/master`.  So after this:
 
 -------------------------------------
@@ -402,8 +402,8 @@ could merge the changes into her master branch:
 alice$ git merge bob/master
 -------------------------------------
 
-This `merge` can also be done by 'pulling from her own remote
-tracking branch', like this:
+This `merge` can also be done by 'pulling from her own remote-tracking
+branch', like this:
 
 -------------------------------------
 alice$ git pull . remotes/bob/master
diff --git a/Documentation/rev-list-options.txt b/Documentation/rev-list-options.txt
index ebc0108..052e64f 100644
--- a/Documentation/rev-list-options.txt
+++ b/Documentation/rev-list-options.txt
@@ -264,7 +264,7 @@ endif::git-rev-list[]
 
 	Pretend as if all the refs in `refs/remotes` are listed
 	on the command line as '<commit>'. If `pattern`is given, limit
-	remote tracking branches to ones matching given shell glob.
+	remote-tracking branches to ones matching given shell glob.
 	If pattern lacks '?', '*', or '[', '/*' at the end is implied.
 
 --glob=glob-pattern::
diff --git a/Documentation/user-manual.txt b/Documentation/user-manual.txt
index 77eb483..cc65077 100644
--- a/Documentation/user-manual.txt
+++ b/Documentation/user-manual.txt
@@ -1700,7 +1700,7 @@ may wish to check the original repository for updates and merge them
 into your own work.
 
 We have already seen <<Updating-a-repository-With-git-fetch,how to
-keep remote tracking branches up to date>> with linkgit:git-fetch[1],
+keep remote-tracking branches up to date>> with linkgit:git-fetch[1],
 and how to merge two branches.  So you can merge in changes from the
 original repository's master branch with:
 
-- 
1.7.2.2.409.gdbb11.dirty


> > (Comment: maybe “... but working directory contains untracked files.”
> > I realise that “directory” is not quite comprehensive here, because
> > files can reside in subdirectories.
> 
> We use "worktree" elsewhere, how about that?

$ git grep "worktree" | wc -l
281
$ git grep "working directory" | wc -l
246
$ git grep "working tree" | wc -l
449

Additionally, "working directory" also really refers to a (current)
working *directory* in many places.

I like "worktree" too, but for consistency I've replaced the
inconsistent usage of "working directory" in the UI with "working
tree". No, I haven't updated the documentation because it's frankly
too painful.

-- 8< --
From 7422c2af1ef40c922d8f628715ad96172e4a5734 Mon Sep 17 00:00:00 2001
From: Ramkumar Ramachandra <artagnon@gmail.com>
Date: Tue, 19 Oct 2010 23:16:04 +0530
Subject: [PATCH] UI: Don't say "working directory" when we really mean "working tree"

While in some places "working directory" is used to refer to the
(current) working directory, it's incorrectly used in places where Git
actually means "working tree" or worktree. Weed out and replace these
instances in the UI.

Reported-by: Thore Husfeldt <thore.husfeldt@gmail.com>
Signed-off-by: Ramkumar Ramachandra <artagnon@gmail.com>
---
 builtin/apply.c      |    2 +-
 convert.c            |    4 ++--
 git-filter-branch.sh |    2 +-
 git-stash.sh         |    2 +-
 setup.c              |    2 +-
 unpack-trees.c       |    2 +-
 wt-status.c          |    4 ++--
 7 files changed, 9 insertions(+), 9 deletions(-)

diff --git a/builtin/apply.c b/builtin/apply.c
index 23c18c5..9166320 100644
--- a/builtin/apply.c
+++ b/builtin/apply.c
@@ -2934,7 +2934,7 @@ static int check_to_create_blob(const char *new_name, int ok_if_exists)
 		if (has_symlink_leading_path(new_name, strlen(new_name)))
 			return 0;
 
-		return error("%s: already exists in working directory", new_name);
+		return error("%s: already exists in working tree", new_name);
 	}
 	else if ((errno != ENOENT) && (errno != ENOTDIR))
 		return error("%s: %s", new_name, strerror(errno));
diff --git a/convert.c b/convert.c
index 01de9a8..441708e 100644
--- a/convert.c
+++ b/convert.c
@@ -131,7 +131,7 @@ static void check_safe_crlf(const char *path, enum action action,
 		 */
 		if (stats->crlf) {
 			if (checksafe == SAFE_CRLF_WARN)
-				warning("CRLF will be replaced by LF in %s.\nThe file will have its original line endings in your working directory.", path);
+				warning("CRLF will be replaced by LF in %s.\nThe file will have its original line endings in your working tree.", path);
 			else /* i.e. SAFE_CRLF_FAIL */
 				die("CRLF would be replaced by LF in %s.", path);
 		}
@@ -142,7 +142,7 @@ static void check_safe_crlf(const char *path, enum action action,
 		 */
 		if (stats->lf != stats->crlf) {
 			if (checksafe == SAFE_CRLF_WARN)
-				warning("LF will be replaced by CRLF in %s.\nThe file will have its original line endings in your working directory.", path);
+				warning("LF will be replaced by CRLF in %s.\nThe file will have its original line endings in your working tree.", path);
 			else /* i.e. SAFE_CRLF_FAIL */
 				die("LF would be replaced by CRLF in %s", path);
 		}
diff --git a/git-filter-branch.sh b/git-filter-branch.sh
index 962a93b..0ab5551 100755
--- a/git-filter-branch.sh
+++ b/git-filter-branch.sh
@@ -110,7 +110,7 @@ OPTIONS_SPEC=
 if [ "$(is_bare_repository)" = false ]; then
 	git diff-files --ignore-submodules --quiet &&
 	git diff-index --cached --quiet HEAD -- ||
-	die "Cannot rewrite branch(es) with a dirty working directory."
+	die "Cannot rewrite branch(es) with a dirty working tree."
 fi
 
 tempdir=.git-rewrite
diff --git a/git-stash.sh b/git-stash.sh
index 7561b37..86cf24e 100755
--- a/git-stash.sh
+++ b/git-stash.sh
@@ -179,7 +179,7 @@ save_stash () {
 
 	git update-ref -m "$stash_msg" $ref_stash $w_commit ||
 		die "Cannot save the current status"
-	say Saved working directory and index state "$stash_msg"
+	say Saved working tree and index state "$stash_msg"
 
 	if test -z "$patch_mode"
 	then
diff --git a/setup.c b/setup.c
index a3b76de..55f8fe3 100644
--- a/setup.c
+++ b/setup.c
@@ -611,7 +611,7 @@ const char *setup_git_directory(void)
 			die_errno ("Could not jump back into original cwd");
 		rel = get_relative_cwd(buffer, PATH_MAX, get_git_work_tree());
 		if (rel && *rel && chdir(get_git_work_tree()))
-			die_errno ("Could not jump to working directory");
+			die_errno ("Could not jump to working tree");
 		return rel && *rel ? strcat(rel, "/") : NULL;
 	}
 
diff --git a/unpack-trees.c b/unpack-trees.c
index 803445a..a70b57c 100644
--- a/unpack-trees.c
+++ b/unpack-trees.c
@@ -934,7 +934,7 @@ int unpack_trees(unsigned len, struct tree_desc *t, struct unpack_trees_options
 
 		}
 		if (o->result.cache_nr && empty_worktree) {
-			ret = unpack_failed(o, "Sparse checkout leaves no entry on working directory");
+			ret = unpack_failed(o, "Sparse checkout leaves no entry on working tree");
 			goto done;
 		}
 	}
diff --git a/wt-status.c b/wt-status.c
index fc2438f..89831cb 100644
--- a/wt-status.c
+++ b/wt-status.c
@@ -95,7 +95,7 @@ static void wt_status_print_dirty_header(struct wt_status *s,
 		color_fprintf_ln(s->fp, c, "#   (use \"git add <file>...\" to update what will be committed)");
 	else
 		color_fprintf_ln(s->fp, c, "#   (use \"git add/rm <file>...\" to update what will be committed)");
-	color_fprintf_ln(s->fp, c, "#   (use \"git checkout -- <file>...\" to discard changes in working directory)");
+	color_fprintf_ln(s->fp, c, "#   (use \"git checkout -- <file>...\" to discard changes in working tree)");
 	if (has_dirty_submodules)
 		color_fprintf_ln(s->fp, c, "#   (commit or discard the untracked or modified content in submodules)");
 	color_fprintf_ln(s->fp, c, "#");
@@ -690,7 +690,7 @@ void wt_status_print(struct wt_status *s)
 				? " (use -u to show untracked files)" : "");
 		else
 			printf("nothing to commit%s\n", advice_status_hints
-				? " (working directory clean)" : "");
+				? " (working tree clean)" : "");
 	}
 }
 
-- 
1.7.2.2.409.gdbb11.dirty


> >    Changes to be committed:
> >    (use "git reset HEAD <file>..." to unstage)
> >
> > should be
> >
> >    Staged to be committed:
> >    (use "git unstage <file>" to unstage)
> 
> This would be extra nice since 'git unstage' could also be used in a
> fresh repository.

[`git unstage` patch still cooking]

Sverre: Thanks!
Thore: Thanks for the feedback. Please read
Documentation/SubmittingPatches and submit more patches.

-- Ram

Re: Git terminology: remote, add, track, stage, etc.

[Jonathan Nieder]

Ramkumar Ramachandra wrote:

> -- 
> 1.7.2.2.409.gdbb11.dirty

Please, one patch per message in the future.

> Sverre Rabbelier writes:
>> On Mon, Oct 18, 2010 at 15:45, Thore Husfeldt <thore.husfeldt@gmail.com> wrote:

>>>    (use "git unstage <file>" to unstage)
>>
>> This would be extra nice since 'git unstage' could also be used in a
>> fresh repository.

My vague unhappiness at "git reset" may have come from this.

Wouldn't it make sense to make "git reset" basically a synonym for
"git rm --cached" when in the 'branch yet to be born' case?

Signed-off-by: Jonathan Nieder <jrnieder@gmail.com>
---
diff --git a/builtin/reset.c b/builtin/reset.c
index 0037be4..cde103f 100644
--- a/builtin/reset.c
+++ b/builtin/reset.c
@@ -236,6 +236,7 @@ static void die_if_unmerged_cache(int reset_type)
 int cmd_reset(int argc, const char **argv, const char *prefix)
 {
 	int i = 0, reset_type = NONE, update_ref_status = 0, quiet = 0;
+	int unborn_branch = 0;
 	int patch_mode = 0;
 	const char *rev = "HEAD";
 	unsigned char sha1[20], *orig = NULL, sha1_orig[20],
@@ -299,13 +300,27 @@ int cmd_reset(int argc, const char **argv, const char *prefix)
 		}
 	}
 
-	if (get_sha1(rev, sha1))
+	if (!strcmp(rev, "HEAD")) {
+		/* We may be on a branch yet to be born. */
+		resolve_ref("HEAD", sha1, 0, NULL);
+		if (is_null_sha1(sha1)) {
+			unborn_branch = 1;
+			commit = NULL;
+			hashcpy(sha1, (const unsigned char *) EMPTY_TREE_SHA1_BIN);
+
+			/* Only accept "git reset -- <paths>" form, for now. */
+			if (i == argc || patch_mode)
+				die("Failed to resolve 'HEAD' as a valid ref.");
+		}
+	} else if (get_sha1(rev, sha1))
 		die("Failed to resolve '%s' as a valid ref.", rev);
 
-	commit = lookup_commit_reference(sha1);
-	if (!commit)
-		die("Could not parse object '%s'.", rev);
-	hashcpy(sha1, commit->object.sha1);
+	if (!unborn_branch) {
+		commit = lookup_commit_reference(sha1);
+		if (!commit)
+			die("Could not parse object '%s'.", rev);
+		hashcpy(sha1, commit->object.sha1);
+	}
 
 	if (patch_mode) {
 		if (reset_type != NONE)

Re: Git terminology: remote, add, track, stage, etc.

[Sverre Rabbelier]

Heya,

On Tue, Oct 19, 2010 at 13:28, Jonathan Nieder <jrnieder@gmail.com> wrote:
> Wouldn't it make sense to make "git reset" basically a synonym for
> "git rm --cached" when in the 'branch yet to be born' case?

Yes, definitely!

-- 
Cheers,

Sverre Rabbelier

Re: Git terminology: remote, add, track, stage, etc.

[Thore Husfeldt]

Also, in the user-manual.txt:

> Examining branches from a remote repository
> -------------------------------------------
> 
> The "master" branch that was created at the time you cloned is a copy
> of the HEAD in the repository that you cloned from.  That repository
> may also have had other branches, though, and your local repository
> keeps branches that track each of those remote branches, which you
> can view using the "-r" option to linkgit:git-branch[1]:
> 
> ------------------------------------------------
> $ git branch -r
>   origin/HEAD
>   origin/html
>   origin/maint
>   origin/man
>   origin/master
>   origin/next
>   origin/pu
>   origin/todo
> ------------------------------------------------
> 
> You cannot check out these remote-tracking branches, but you can
> examine them on a branch of your own, just as you would a tag:

That’s just wrong, isn’t it? You absolutely can check out a remote-tracking branch.

User manual: "You cannot check out these remote-tracking branches"

[Jonathan Nieder]

Thore Husfeldt wrote:

> Also, in the user-manual.txt:
[...]
>>   origin/todo
>> ------------------------------------------------
>> 
>> You cannot check out these remote-tracking branches, but you can
>> examine them on a branch of your own, just as you would a tag:
>
> That’s just wrong, isn’t it?

That's historical baggage, I'm afraid.

Signed-off-by: Jonathan Nieder <jrnieder@gmail.com>
---
diff --git a/Documentation/user-manual.txt b/Documentation/user-manual.txt
index 77eb483..9f82fa6 100644
--- a/Documentation/user-manual.txt
+++ b/Documentation/user-manual.txt
@@ -359,13 +359,16 @@ $ git branch -r
   origin/todo
 ------------------------------------------------
 
-You cannot check out these remote-tracking branches, but you can
-examine them on a branch of your own, just as you would a tag:
+You might want to build on one of these remote-tracking branches
+on a branch of your own, just as you would a tag:
 
 ------------------------------------------------
 $ git checkout -b my-todo-copy origin/todo
 ------------------------------------------------
 
+You can also check out "origin/todo" directly to examine it or
+write a one-off patch.  See <<detached-head,detached head>>.
+
 Note that the name "origin" is just the name that git uses by default
 to refer to the repository that you cloned from.
 

Re: Git terminology: remote, add, track, stage, etc.

[Nicolas Pitre]

[-- Attachment #1: Type: TEXT/PLAIN, Size: 1634 bytes --]

On Tue, 19 Oct 2010, Thore Husfeldt wrote:

> Also, in the user-manual.txt:
> 
> > Examining branches from a remote repository
> > -------------------------------------------
> > 
> > The "master" branch that was created at the time you cloned is a copy
> > of the HEAD in the repository that you cloned from.  That repository
> > may also have had other branches, though, and your local repository
> > keeps branches that track each of those remote branches, which you
> > can view using the "-r" option to linkgit:git-branch[1]:
> > 
> > ------------------------------------------------
> > $ git branch -r
> >   origin/HEAD
> >   origin/html
> >   origin/maint
> >   origin/man
> >   origin/master
> >   origin/next
> >   origin/pu
> >   origin/todo
> > ------------------------------------------------
> > 
> > You cannot check out these remote-tracking branches, but you can
> > examine them on a branch of your own, just as you would a tag:
> 
> That’s just wrong, isn’t it? You absolutely can check out a remote-tracking branch.--

Yes, the above is wrong.  But to check out a remote-tracking branch, or 
a tag, or a random commit through its SHA1, we do rely on the concept of 
a "detached head".  That term and concept has caused newbies grief in 
the past as well, despite the fact that seasoned Git users are perfectly 
fine with it.

A detached head is HEAD not being linked to any branch.  This is done 
because tags and remote-tracking branches are not meant to be altered by 
local changes.  Hence committing stuff on top of a detached head will 
advance HEAD, but no actual branch is keeping a record of it.


Nicolas

Re: Git terminology: remote, add, track, stage, etc.

[Junio C Hamano]

Jonathan Nieder <jrnieder@gmail.com> writes:

> Wouldn't it make sense to make "git reset" basically a synonym for
> "git rm --cached" when in the 'branch yet to be born' case?

Hmm,...

While you are on 'master', shouldn't these behave identically?

    $ git reset master -- frotz.c
    $ git reset HEAD -- frotz.c
    $ git reset -- frotz.c

while shouldn't this fail if there is no 'naster' branch?

    $ git reset naster -- frotz.c

It is probably Ok to limit the scope of this change to the case without
any explicit rev, e.g. "git reset -- frotz.c", but at that point I somehow
don't think it will reduce confusion but rather will make things worse.

> +	if (!strcmp(rev, "HEAD")) {

Comparing the address of the "HEAD" used for initialization with rev may
make sure that the code will catch only "no explicit rev" case here, but
that is not what is happening here, which is even less consistent.

Re: User manual: "You cannot check out these remote-tracking branches"

[Matthieu Moy]

Jonathan Nieder <jrnieder@gmail.com> writes:

> -You cannot check out these remote-tracking branches, but you can
> -examine them on a branch of your own, just as you would a tag:
> +You might want to build on one of these remote-tracking branches
> +on a branch of your own, just as you would a tag:

Shouldn't this be "just as you would _for_ a tag"?

-- 
Matthieu Moy
http://www-verimag.imag.fr/~moy/

Re: Git terminology: remote, add, track, stage, etc.

[Jakub Narebski]

Re-added (some of) CC list; at least all quoted authors are there.

Thore Husfeldt <thore.husfeldt@gmail.com> writes:

> Thank you all for your many and well-thought out replies. I learned
> a lot.
> 
> Jonathan Nieder:
> 
> JNi> So what would be a better term [for tracking]?
> 
> Trailing is better than tracking, since it hints at some degree of
> sloth, but I have not thought this through. (I also think that it
> may be a strategic mistake to advocate looking for a new name; as
> long as tracking is used consistently the problem with a misleading
> metaphor is not so big, and the name change alienates a large group
> of people whose consent is important.)

It is harder to use as adjective though, compare "remote-tracking
[branch]" with "remote-trailing [branch]"... or is it just "trailing
branch"?

Besides I don't think that 'remote-tracking' has to mean
_automatically_ tracking; it is *used* to track.

> Matthiey Moy:
> 
> MM> Git's huge sin, after all (judging from most complaints I see
> MM> about it), is that It Doesn't Use Exactly The Same Model (and
> MM> thus Terminology) That CVS Did...
> 
> 
> My analysis of Git’s wickedness is interestingly different. Git has
> a clean and simple model that should be very easy to
> understand.

The unfortunate consequence of this is that many git command and much
of git documentation is based on this understanding.  It would be
better to have documentation centered around 'user stories', not
techicalities.

For example instead of `git unstage <file>`, one has to use 
`git reset -- <file>`; one has to understand how contents is moved
between repository (commits), staging area (index / cache) and
worktree to arrive at this command.  Fortunately `git status`
and the comments in commit message template help users there,
but it would be nice not to have to rely on this.

> Git’s rhetorical traditions prevent that understanding. Git is
> really, really hard to learn, no matter where you come from, but
> there is no inherent reason for that.

Well, there is a matter of debate how much of git complexity is
accidental complexity which should be eliminated, and how much is
essential complexity.

For example user-visible staging area[1], or git branching model[2]
can be confusing, at least to users coming from other version control
systems.  Those concepts though are necessary to allow much of power
of git.  In the case of visible staging area dealing with conflicts
during merge and choosing piece-by-piece what is to be in next commit.
In the case of git branching model, it allows for interacting with
multiple multi-branch repositories without worrying about single
global namespace for branch names.


[1] Other version control systems have at least a shadow of it,
    because they need to know which files are to be versioned
    (tracked).

[2] I mean here the difference between refs/heads/* and
    refs/remotes/<remote>/* refs, and mapping between tracked branches
    in remote repository and remote-tracking branches in given
    repository.
 
> The steepness of the learning curve (rather than the divergence from
> other systems’s terminology) is the single biggest complaint against
> git, evidenced by my own anecdotal evidence from web surfing, and by
> the Git user survey. It should be viewed as Git’s biggest current
> problem by an order of magnitude. It makes me think twice and thrice
> before asking my colleagues to collaborate with me using Git; I will
> probably learn Mercurial and advocate using that instead; it’s
> almost as nice, and I don’t feel embarrassed advocating it. Using
> git for myself is great (now I understand it) but it is unclear if I
> should invest social capital to convince others to use it as well.

I guess that some of _perceived_ ease of use of Mercurial was
generated by the fast that (at least in the past) it had superior
documentation in the form of "Mercurial: The Definitive Guide" aka
hgbook.  Though nowadays there is "Git User's Manual" and "Pro Git",
it is hard to fight prejudice.

> Sverre Rabbelier:
> 
> SR> What do you mean with the last part (about `git branch -r`)? The
> SR> fact that 'refs/remotes' is not immutable?
> 
> Well, consider for example the simple obfuscatory mastery of the
> following line in the user manual:
> 
> > $ git branch -r			# list all remote branches

So you say that it should be instead the following, isn't it?

>   $ git branch -r		# list all remote-tracking branches


> 
> 
> Yes, I get it *now*. And I begin to feel the corruption spreading in
> my own brain already: I myself start to think of origin/master as a
> ``remote branch''. Give me a few more weeks and I will be
> completely assimilated in the mindset.
> 
> (Note to self: submit a patch about this before my assimilation is
> complete. I already fixed it and committed to my local branch.)

That would be very nice.

> 
> Matthieu again:
> 
> MM> We already came up with a better wording, namely "upstream", and
> MM> used in in "git push --set-upstream".
> 
> Oh, I didn’t know that. I was convinced that "upstream" was
> cruft from when git was chiefly a tool to help Linus maintain the
> Linux kernel. Let's see if I get this right:
> 
> The remote-tracking branch "origin/master" is *upstream* (the
> upstream?) of the local branch "master",

Right.

> and [local branch "master"] *tracks* the remote origin’s branch
> "master"? (local) "master" is downstream of "origin/master"?

With above clarification: right.  Though using "track" here was
mistake ("follows" or "is downstream").

> 
> This would be useful. And @{u} is good. (Does it have an inverse?)

One branch can have only one "upstream" (in old terminology: it can
track only one branch).  But the reverse doesn't hold: single
remote-tracking branch can be upstream for many branches (e.g. many
feature branches based on the same long-lived branch).  The mapping is
one-to-many, so there is no inverse.

> 
> I’m not sure I like the particular word, but that’s a minor complaint. 
> 
> ( For completeness: A small terminological quibble is that upstream
> doesn’t verb well.

That's why git has `--set-upstream` ;-)

> A bigger conceptual quibble is that this decision is not
> workflow-neutral. It enforces git’s hierarchical linux-kernel
> development tradition, rather than embracing a truly distributed
> model where everybody is the same. When I think of distributed
> version control I like to think of Alice having a remote-tracking
> bob/master and Bob having a remote-tracking alice/master. Of course,
> it is still meaningful for Alice to say "the upstream of
> bobs_latest_crazy_ideas is bob/master", and for Bob to say "the
> upstream of alices_inane_ramblings is alice/master". But it
> introduces a notion of hierarchy that is inimical to the concept of
> distribution, and not workflow-neutral. )

Actually it is inimical to pull-based workflow, not to hierarchical
development.  "Upstream" is where you pull from.

Sidenote: having 'canonical' repository that (almost) everybody pulls
from is I think quite common in DVCS-based development, isn't it?

> 
> Of course, upstream could be called supercalifragilistic and I would
> still like it. Consistency is more important than having good
> metaphors. (But good metaphors would be better, all other things
> being equal.)
> 
> Jakub Narebski:
> 
> JNa> Note that it is not as easy as it seems at first glance.  There
> JNa> are *two* such options, which (as you can read in gitcli(7)
> JNa> manpage) have slightly different meaning:
> 
> Wow. Thanks for pointing this out, I did not know that, and it
> explains a lot. I must say that to everybody else than a git
> developer, this state of affairs is a proof that something is wrong,
> rather than an obstruction for improvement.

What I wanted to say that any proposal for replacing 'cache'/'cached'
and 'index' terms has to take into account that you might want to
operate on staging area *instead of* default target (`--cached`),
or *in addition to* default target (`--index`).

Though it is not widespread issue: only git-apply uses both --cached
and --index, git-stash uses only --index, and all other commands use
only --cached (if any).

Well, there is also outlier of `git diff --no-index`, but it is more
lack of good name for an option :-P

> 
> ??> I do not think debating on changing the terminology is a
> ??> particularly productive use of our time.
> 
> I agree in the sense that *how* the words are used is more important
> than *which* words are used, and I realise that I should not have
> put "terminology" in the headline, because that makes it about
> words, not *explanations* or terminological *discipline*.

What should you put in headline / subject, then?

-- 
Jakub Narebski
Poland
ShadeHawk on #git

Re: Git terminology: remote, add, track, stage, etc.

[Drew Northup]

On Mon, 2010-10-18 at 22:45 +0200, Thore Husfeldt wrote:
> I’ve just learned Git. What a wonderful system, thanks for building
> it. 
> 
> And what an annoying learning experience. 

I have to admit having dealt with quite a few annoyances, but mostly
because I'm attempting to implement new functionality into this
project--something that requires minimally groking the sections of code
that I propose to change. (Anything less is sheer idiocy--and this is a
crowd that would not hesitate to say so.)

> I promised myself to try to remember what made it all so hard, and to
> write it down in a comprehensive and possibly even constructive
> fashion. Here it is, for what it’s worth. Read it as the friendly, but
> somewhat exasparated suggestions of a newcomer. I’d love to help (in
> the form of submitting patches to the documentation or CLI responses),
> but I’d like to test the waters first.
> 
> So, in no particular order, here are the highlights of my former
> confusion, if only for your entertainment. Comments are welcome, in
> particular where my suggestions are born out of ignorance.

As a user and survivor of other source code management, collaboration,
and versioning systems (not to mention some OS/X Windows/uC/CPU innards)
I did not find git nearly as jolting as you appear to have. I suspect
this will be clear in following discussions.

> Remote (tracking) branches
> --------------------------
> 
> There are at least two uses of the word *tracking* in Git's
> terminology.
> 
> The first, used in the form “git tracks a file” (in the sense that Git
> knows about the file) is harmless enough, and is handled under `git
> add` below.
> 
> But the real monster is the *tracking branch*, sometimes called the
> remote branch, the remote-tracking branch, or the remote tracking
> branch. Boy did that ever confuse me. And, reading the git mailing
> list and the web, many others. There are so many things wrong with how
> this simple concept is obfuscated by the documentation that I have a
> hard time organising my thoughts about writing it down.
> 
> Please, *please* fix this. It was the single most confusing and
> annoying part of learning Git.
> 
> First, the word, “tracking”. These branches don’t track or follow
> anything. They are standing completely still. Please believe me that
> when first you are led to believe that origin/master tracks a branch
> on the remote (like a hound tracks it quarry, or a radar tracks a
> flight) that it is very difficult to hunt this misunderstanding down:
> I believed for a long time that the tracking branch stayed in sync,
> automagically, with a synonymous branch at the remote. The CLI and
> documentation worked very hard to keep me in that state of
> ignorance. I *know* that my colleague just updated the remote
> repository, yet the remote branch (or is the remote tracking branch?
> or the remote-tracking branch?) is as it always was...? (How could I
> *ever* believe that? Well, *now* I get it, and have a difficult time
> recollecting that misunderstanding. *Now* it’s easy.)

Two things here: 
(1) The meaning of "tracking" in context differs from your abstract
notion of tracking. Perhaps the metaphor is better seen as the
"tracking" of wild game animals--you follow their footprints, grazing
marks, paths, and scat (viewed with gitk ? ;-) ) yet only once in a
while can you reach out and "pull" on them (at least one doesn't have to
shoot things to make git work--although it might help on some days).

(2) Hyphenation should, in theory, be consistent. I do not however
expect this to be completely automatic in a population of code authors
which contains a great deal of non-native speakers of English
(conceivably some people here may even read and write English without
feeling competent to speak it out loud). Due to this reality I usually
keep my inner "Grammar Nazi" in check with free/open software projects.
This does not make the documentation any easier to read, it just keeps
me from breaking things while I do. 
As an aside, whose "English" are we to deem nominally correct--ASE, BSE,
ISE, or perhaps so-called "Singapore English" (which is actually spoken
other places as well)? Just because American Standard English currently
has (eroding) hegemony in the software documentation sphere (from my
perspective) does not grant me some special platform to shove it down
the throats of others. Thankfully clarification of hyphenation by
introducing consistency is likely to be universally received in a
positive light.

> Second, the word “remote” as opposed to “local”, a dichotomy enforced
> by both the documentation and by the output of `git branch -r` (list
> all remote branches, says user-manual.txt). Things began to dawn on me
> only when I understood that origin/master is certainly and absolutely
> a “local” branch, in the sense that it points to a commit in my local
> repository. (It differs from my other local branches mainly in how it
> is updated. It’s not committed to, but fetched to. But both are local,
> and the remote can be many commits ahead of me.)
> 
> So, remote tracking branches are neither remote (they are *local*
> copies of how the remote once was) and they stand completely still
> until you tell them to “fetch”. So remote means local, and tracking
> means still, “local still-standing” would be a less confusing term
> that “remote tracking”. Lovely.

This is one area in which excessive steeping in the handling, care,
feeding, and management of other SCM systems would help understand what
git is up to.

The "origin/master" is seen semantically as a locally stashed but not
intended to be used directly "copy" of the origin's master--you create a
local branch for that--in your local object store. This apparent copy
can be thought of better perhaps as a pointer into the object store to
call upon the "origin/master" locally-stored state (origin's master as
your local object store remembers it). It can be used to follow changes
made to the remote--origin's--master (but one is not forced to do so).
Often times it may be found mirrored in (more correctly, merged into)
the local branch named "master"--which you created, most likely via
cloning. Therefore it can be confusing at some level--at first--to
realize that "origin/master" and "master" are not the same thing yet may
sure appear to be. Once you take the pointer for what it is this makes a
bit more sense. (This is why you can "git checkout origin/master" if you
want...)
Taking this metaphor one step further, we DE-REFERENCE and merge
"origin/master" into "master" (or whatever you named your
"remote-tracking" branch) as the last bulk operation when executing a
"pull" on master. This is explained fairly clearly (in my mind) in the
documentation as a convenience melding of a "git fetch"--origin's master
(remote) is copied into the local object store as "origin/master"--and a
"git merge origin/master" executed while checked-out as the local copy
of the branch you are tracking (you probably named it master).

> Tracking branches *track* in the sense that a stuffed Basset Hound
> tracks. Namely, not. It‘s a dream of what once was.

YES!!! Ok, well, except for the stuffed part. Never have your dog
stuffed (ask Alan Alda, or read his book of the same name).

> The hyphenated *remote-tracking* is a lot better terminology already
> (and sometimes even used in the documentation), because at least it
> doesn't pretend to be a remote branch (`git branch -r`, of course,
> still does). So that single hyphen already does some good, and should
> be edited for consistency. (It did take time for me to convince myself
> during the learning process that “remote tracking” and
> “remote-tracking” probably are the same thing, and “tracked remote”
> something else, abandoning and resurrecting these hypetheses several
> times.)

This, I'm sure, can be rectified with minimum pain. Recall my note above
about non-native speakers. I don't expect them (or for that matter most
native speakers) to be in the habit of making use of English punctuation
tools that most American Language-Arts teachers don't seem to have
mastered either. Heck, I'll readily admit that I only got a 3 (of 5) on
the English Language AP Exam, so there are obviously some aspects of the
"official" language known to the cognoscenti that I still don't grok
either.

> And *even if* the word was meaningful and consistenly spelt, the
> documentation uses it to *refer* to different things. Assume that we
> have the branches master, origin/master, and origin’s master
> (understanding that they exist, and are different, is another Aha!
> moment largely prevented by the documentation). For 50 points, which
> is the remote tracking branch? Or the remote-tracking branch? 

Let's not make a big deal about the hyphen in that case for now.

> The remote branch? 

That would be origin's branch (whatever it is named and whoever "origin"
is in this case).

> Which branch tracks which other branch? 

Our local origin/<branch> is our local object store's memory of what it
last knew origin's branch to look like.

> Does master track anything? 

Per-Se, No. Can it be merged with our latest fetch into the object store
of origin's (origin/...)? Yes. Can it be done with one nice convenient
wrapper command in the current git? Yes!

> Nobody seems to know, and documentation and CLI
> include various inconsistent suggestions. (I know there have been
> long, and inconclusive threads about this on the git mailing list, and
> I learned a lot from seeing other people’s misconceptions mirror my
> own.)  Granted, I think the term “tracked remote branch” is used with
> laudable consistentcy to refer to a branch on the remote. And “remote
> tracking branch” (with our without the hyphen) more often than not
> refers to origin/master. It may be that terminology is slowly
> converging. (To something confusing, but still...)

Remember, remote branches other than "master" may be tracked. For
instance, if you are tracking git with git then you are also tracking
branches named html, todo, maint, man, pu, and next--yet you may not
have created a local remote-tracking branch for them to reside in
locally.

> But to appreciate how incredibly difficult this was to understand,
> check this, from the Git Community book:
> 
>     A 'tracking branch' in Git is a local branch that is connected to
>     a remote branch.
> 
> To a new user, who *almost* gets it, this is just a slap in the
> face. Which one of these is origin/master again? None? (Or rather, it
> is the confirmation one needs that nobody in the Git community cares
> much, so the once-believed-to-be-carefully-worded documentation loses
> some of its authority and therefore the learner can abandon some
> misunderstandings.)

Again, the author's sense of "connected" and your internal sense of
"connected" did not match--much like "tracking" earlier (and below). He
is not stating that they are bound at the hip, he is merely noting the
presence of a conceptual relationship between the two. It could have
been stated differently perhaps, but it is not the end of the world.

> There probably is a radical case to be made for abandoning the word
> “tracking” entirely. First, because tracking branches don’t track, and
> second because “tracking” already means something else in Git (see
> below). I realise that this terminology is now so ingrained in Git
> users that conservatism will probably perpetuate it. But it would be
> *very* helpful to think this through, and at least agree on who
> “tracks” what. In the ideal world, origin/master would be something
> like “the fetching branch” for the origin’s master, or the “snapshot
> branch” or the “fetched branch”. (I am partial to use “fetching”
> because it makes that operation a first-class conceptual citizen,
> rather than pulling, which is another siren that lures newbies into a
> maelstroem of confusion.)

Umm, NO. Tracking is a term that is used consistently in most places. It
means "following by collecting information about" as I noted earlier
with my wild game animals example. This is true throughout whether that
being tracked is a file's contents, an entire branch's contents, or the
contents of a whole repository. That you have mis-associated the concept
of tracking with that of fetching the information used to perform that
tracking (and remembering from where and how to do so) is perhaps
something that can be dealt with but it does not require abandoning what
is frankly a useful metaphor. (Besides "fetching" in isolation begs
confusion with other concepts such as a "comely lass"--the great wonder
of the English language indeed.)

> More radically, I am sure some head scratching would be able to find
> useful terminology for master, origin/master, and origin’s master. I’d
> love to see suggestions. As I said, I admire how wonderfully simple
> and clean this has been implemented, and the documentation, CLI, and
> terminology should reflect that.

I did not find the terminology particularly jarring, but I have used
(and survived doing so) other SCM software. Perhaps you did not have any
previous SCM background? More information as to the source of confusion
and your perspective when starting out can only help improve the
documentation.

> The staging area
> ----------------
> 
> The wonderful and central concept of staging area exists under at
> least three names in Git terminology. And that’s really, really
> annoying. The index, the cache, and the staging area are all the same,
> which is a huge revelation to a newcomer.

Not true. When merging the index may contain multiple staged instances
of any given content needed to resolve conflicts for instance. Also, the
cache is stored inside of the index. Therefore while they may at any
given time have exactly the same contents they are not the same things
nor concepts.

> *Index* would have been a good word for the files known
> to Git (what is now called, sometimes, “tracked files”)

Index is used to refer to the mechanism by which the currently operative
CONTENT known to git. Git does not track files per-se, it tracks
CONTENT. This is an important distinction to master. It literally
indexes the contents to be operated upon in the object store. That those
contents happen to exist in files is something it keeps track of but it
really could care less. So far is it is concerned they could be show
tunes.

> `git stage` is already part of the distribution. Great.
> 
> 1. Search for index and cache in the documentation and rephrase any
> and all their occurences to use “staged” (or, if it can’t be avoided
> “the staging area”) instead. Say “staged to be committed” often, it’s
> a strong metaphor.

No. The documentation should not be made incorrect just to make it sound
more consistent.

> 2. Introduce the alias `git unstage` for `git reset HEAD` in the
> standard distribution.

This is evidence to me that you have not used other SCM software. The
idiom "reset" is widely used in various SCM implementations.

> 3. Duplicate various occurences of `cached` flags as `staged` (and
> change the documentation and man pages accordingly), so as to have,
> e.g., `git diff --staged`.

Again, cached is not staged and flags should not be made incorrect just
to cover for the fact that you have not found a use for them separately.

> git status
> ----------
> 
> One of the earliest-to-use commands is `git status`, whose message are
> *wordy*, but were initially completely unhelpful to me. In particular,
> 
>    working directory clean
> 
> Clean? What’s this now? Clean and dirty are Git slang, and not what I
> want to meet as a new user. 

This is not git-specific jargon. In fact, it is widely used terminology
throughout the computing world in memory management, databases,
filesystems, and even other SCM platforms. I have even heard it used by
non-computer-oriented people to refer to original and changed states.

> The message should inform me that the
> untracked files in the working directory are equal to their previous
> commit. But there are other things wrong with the message. 

Actually, what it is stating is correct. It knows NOTHING about any
untracked files OTHER THAN that they have not changed since the last
commit. In other words, the POTENTIAL INDEX is clean of unwritten
changes. 

> For
> example, even though there’s nothing to commit: `nothing added to
> commit but untracked files present (use "git add" to track)`? The last
> paranethesis should set off warning bells already. And what did clean
> mean with respect to untracked files? And “added to commmit”? That
> sounds like amending. We add to the index or the staging area, don’t
> we, “ready to be included in the next commit,” so they aren’t added to
> that commit quite yet?

This is analogous to files having been changed inside of an application
yet the application has not yet requested that such changes be scheduled
to be committed to the filesystem. You have to request that such changes
be added to the filesystem layer's idea of what needs to be committed
and then it will be written out in due time. The same thing applies to
git's index and the object store.

> 
>     changed but not updated:
> 
> I’m still not sure what “update” was ever supposed to mean in this
> sentence. I just edited the file, so it’s updated, for crying out
> loud! The message might just say “Changed files, but not staged to be
> committed.”  

In this case you have already scheduled some changes of a file to be
committed in the index and then have gone and made additional changes
without updating the index. So no, it isn't updated yet--but there are
changes staged to be committed for the very same files.

> The meant-to-be helpful “use [...] to update what will be
> committed” is another can of worms, and I can find at least two ways
> to completely misunderstand this. Change to “use `git stage <file>` to
> stage”. (With the new command name it’s almost superfluous.)

Here is where a proper discussion of why it is called "git add <file>"
comes into play. When you use the add operation you are literally adding
he current status of that file to the index. If you make another change
to that file before committing you will need to add that new status of
the file. In other words, you have staged the changes to the content in
that file to be committed twice into the index at two different times
and with two different change-sets.

> Here are some concrete suggestions:
> 
> 1.
> 
>     nothing added to commit but untracked files present
> 
> should be
> 
>     nothing staged to commit, but untracked files present
> 
> (Comment: maybe “... but working directory contains untracked files.”
> I realise that “directory” is not quite comprehensive here, because
> files can reside in subdirectories. But I’d like to be more concrete
> than “be present”.)

The concept of "present" is fine in this case, just like being present
at a meeting. The comma is useful perhaps to some but may not be
grammatically correct here. As for "added" versus "staged" that depends
on the circumstances. I am having trouble coming up with an example off
the top of my head as to how to explain when "added" and "staged" differ
in meaning I am sure the do (perhaps upon the deletion of a tracked
file?).

> 2.
>     Untracked files:
>     (use "git add <file>..." to include in what will be committed)
> 
> should be
> 
>     Untracked files:
>     (use "git track <file>" to track)

This is not helpful. Git does not work the way that Subversion does. In
other words, each content change must be manually added to the index for
staging to build a commit for each and every commit. Files and their
contents ARE NOT tracked perpetually (touching on earlier noted
confusion about the context-specific meaning of track). We should not
encourage confusion on this matter.

> 3.
> 
>     Changes to be committed:
>     (use "git reset HEAD <file>..." to unstage)
> 
> should be
> 
>     Staged to be committed:		 
>     (use "git unstage <file>" to unstage)

Again, "reset" is a widely used metaphor in SCM software and there is no
good reason to abandon it. What you are proposing is not even a 1:1
replacement. The original command quite literally does the following
"reset index information about <file> to HEAD" while what you propose
merely says "remove staged change about <file> from the index." What if
<file> has been changed and staged to commit more than once? The
proposed syntax is ambiguous and therefore is a poor replacement.

> Adding
> ------
> 
> The tutorial tells us that 
> 
>     Many revision control systems provide an add command that tells
>     the system to start tracking changes to a new file. Git's add
>     command does something simpler and more powerful: git add is used
>     both for new and newly modified files, and in both cases it takes
>     a snapshot of the given files and stages that content in the
>     index, ready for inclusion in the next commit.
> 
> This is true, and once you grok how Git actually works it also makes
> complete sense. “Making the file known to Git” (sometimes called
> “tracking the file”) and “staging for the next commit” result in the
> exact same operations, from Git’s perspective.

Not exactly. You forget that git is not stateless. A file may be "known
to git" yet not changed (much less staged) since the last commit. Also,
git does not track changes perpetually--it only updates it's idea
(index) of changes to be committed (stages) when asked. It could be said
that it tracks changes incrementally upon request.

> But this is a good example of what’s wrong with the way the
> documentation thinks: Git’s implementation perspective should not
> define how concepts are explained. In particular, *tracking* (in the
> sense of making a file known to git) and *staging* are conceptually
> different things. In fact, the two things remain conceptually
> different later on: un-tracking (removing the file from Git’s
> worldview) and un-staging are not the same thing at all, neither
> conceptually nor implementationally. The opposite of staging is `git
> reset HEAD <file>` and the opposite of tracking is -- well, I’m not
> sure, actually. Maybe `git update-index --force-remove <filename>`?
> But this only strenghtens my point: tracking and staging are different
> concepts, and therefore deserve different terms in the documentation
> and (ideally) in the CLI.

As tracking of changes is in part the art of remembering those changes
and making such changes available for inspection upon request (see my
"wild game" metaphor above) the way a detective might "track" evidence
there is no need to conflate the incremental tracking of some changes
before committing them with the list of changes we have tracked into the
object store in the past. This is part of the power of git. It tells you
what content changed when and where that change came from. It "tracked"
all of them. It does not "track" mere files. It tracks CONTENT. When git
"stages" changes it tracks them in its short-term memory (the index) and
when it commits those staged changes to the object store it allows
itself to track them for all time (conceptually).

> The entire quoted paragraph in the tutorial can be removed: there’s
> simply no reason to tell the reader that git behaves differently from
> other version control systems (indeed, to take some perverse *pride*
> in that fact). 

In fact it is very worth noting that git works differently from other
SCM software. Not knowing what is different leads to a series of
important and potentially disastrous misconceptions. It should take
pride in being different, as it implements the holy grail of SCM: being
able to know who changed what, when, and perhaps even why.

> An even more radical suggestion (which would take all of 20 seconds to
> implement) is to introduce `git track` as another alias for `git
> add`. (See above under `git status`). This would be especially useful
> if tracking *branches* no longer existed.

This is not appropriate. Git is not Subversion. It does not track files
for all time and it is not stateless. Full Stop.

> There’s another issue with this, namely that “added files are
> immediately staged”. In fact, I do understand why Git does that, but
> conceptually it’s pure evil: one of the conceptual conrnerstones of
> Git -- that files can be tracked and changed yet not staged, i.e., the
> staging areas is conceptually a first-class citizen -- is violated
> every time a new file is “born”. Newborn files are *special* until
> their first commit, and that’s a shame, because the first thing the
> new file (and, vicariously, the new user) experiences is an
> aberration. I admit that I have not thought this through.--

????? This strikes me as a vast misunderstanding of the mechanism at
work. If you could describe the roots of this idea then perhaps it could
be addressed. Git is not your filesystem.

Hopefully the couple of hours I spent on this helps further this
discussion in a useful manner.

-- 
-Drew Northup
________________________________________________
"As opposed to vegetable or mineral error?"
-John Pescatore, SANS NewsBites Vol. 12 Num. 59

[RFC/PATCH 0/4] reset: be more flexible about <rev>

[Jonathan Nieder]

Junio C Hamano wrote:

> It is probably Ok to limit the scope of this change to the case without
> any explicit rev, e.g. "git reset -- frotz.c", but at that point I somehow
> don't think it will reduce confusion but rather will make things worse.

I wouldn't be surprised to find people using

	git reset HEAD <paths>

just because '--' did not come to mind quickly enough.  For example, I
have a faint memory of doing that myself a couple of years ago.  Why
should Git mind?

Patch 1 below teaches reset -p to accept an arbitrary tree for <rev>.
Unfortunately add--interactive notices but does not error out when
<rev> is a blob; that should be fixed in the add--interactive script
by checking the exit status of commands it runs, I think (help from
those more comfortable in perl would be appreciated).

Patch 2 removes the arbitrary restriction in "git reset <rev>
<path>" that <rev> be a commit.  It also paves the way for writing
patch 3 more clearly.

Patch 3 is the "probably Ok" change you mentioned above.  It allows
use of "git reset" to un-add a file from an unborn branch.

Patch 4 is like patch 3, but for "git reset HEAD".

Help on finishing up patch 1 (or comments to the effect that it is
pointless) would be welcome.

Jonathan Nieder (4):
  reset -p: accept "git reset -p <tree>"
  reset: accept "git reset <tree> <path>"
  reset: accept "git reset -- <path>" from unborn branch
  reset: accept "git reset HEAD <path>" from unborn branch

 builtin/reset.c         |   27 ++++++++++++++++-------
 t/t7102-reset.sh        |   31 +++++++++++++++++++++++++++
 t/t7105-reset-patch.sh  |   12 ++++++++++
 t/t7106-reset-unborn.sh |   53 +++++++++++++++++++++++++++++++++++++++++++++++
 4 files changed, 115 insertions(+), 8 deletions(-)
 create mode 100755 t/t7106-reset-unborn.sh

-- 
1.7.2.3

[WIP/PATCH 1/4] reset -p: accept "git reset -p <tree>"

[Jonathan Nieder]

When reset -p was implemented (v1.6.5-rc0~5^2~7, 2009-08-15), it
piggy-backed on an existing "git reset" check to verify that the
<rev> argument represents a valid commit.  By dropping that
check, we can use reset -p to apply changes from an arbitrary
tree; for example, from the linux-2.6 tree:

	git reset -p 2.6.11 -- Makefile

add--interactive already rejects invalid refs.

	$ git init >dev/null 2>&1; git reset -p HEAD; echo $?
	fatal: ambiguous argument 'HEAD': unknown revision or path not in the working tree.
	Use '--' to separate paths from revisions
	128

Unfortunate side-effect: reset -p will accept a blob for <rev>,
too.

	$ git reset -p HEAD:git.c; echo $?
	error: bad tree object HEAD:git.c
	No changes.
	0

Signed-off-by: Jonathan Nieder <jrnieder@gmail.com>
---
 builtin/reset.c        |   12 ++++++------
 t/t7105-reset-patch.sh |   12 ++++++++++++
 2 files changed, 18 insertions(+), 6 deletions(-)

diff --git a/builtin/reset.c b/builtin/reset.c
index 0037be4..a52e6f8 100644
--- a/builtin/reset.c
+++ b/builtin/reset.c
@@ -297,24 +297,24 @@ int cmd_reset(int argc, const char **argv, const char *prefix)
 			/* Otherwise we treat this as a filename */
 			verify_filename(prefix, argv[i]);
 		}
 	}
 
+	if (patch_mode) {
+		if (reset_type != NONE)
+			die("--patch is incompatible with --{hard,mixed,soft}");
+		return interactive_reset(rev, argv + i, prefix);
+	}
+
 	if (get_sha1(rev, sha1))
 		die("Failed to resolve '%s' as a valid ref.", rev);
 
 	commit = lookup_commit_reference(sha1);
 	if (!commit)
 		die("Could not parse object '%s'.", rev);
 	hashcpy(sha1, commit->object.sha1);
 
-	if (patch_mode) {
-		if (reset_type != NONE)
-			die("--patch is incompatible with --{hard,mixed,soft}");
-		return interactive_reset(rev, argv + i, prefix);
-	}
-
 	/* git reset tree [--] paths... can be used to
 	 * load chosen paths from the tree into the index without
 	 * affecting the working tree nor HEAD. */
 	if (i < argc) {
 		if (reset_type == MIXED)
diff --git a/t/t7105-reset-patch.sh b/t/t7105-reset-patch.sh
index 9891e2c..ba3ff42 100755
--- a/t/t7105-reset-patch.sh
+++ b/t/t7105-reset-patch.sh
@@ -46,10 +46,22 @@ test_expect_success PERL 'git reset -p dir' '
 	(echo y; echo n) | git reset -p dir &&
 	verify_state dir/foo work head &&
 	verify_saved_state bar
 '
 
+test_expect_success PERL 'git reset -p <tree> dir' '
+	set_state dir/foo work work &&
+	(echo y; echo n) | git reset -p HEAD^{tree} dir &&
+	verify_state dir/foo work head &&
+	verify_saved_state bar
+'
+
+test_expect_failure PERL 'git reset -p <blob>' '
+	set_state dir/foo work work &&
+	test_must_fail git reset -p HEAD:dir/foo
+'
+
 test_expect_success PERL 'git reset -p -- foo (inside dir)' '
 	set_state dir/foo work work
 	(echo y; echo n) | (cd dir && git reset -p -- foo) &&
 	verify_state dir/foo work head &&
 	verify_saved_state bar
-- 
1.7.2.3

[PATCH 2/4] reset: accept "git reset <tree> <path>"

[Jonathan Nieder]

The <rev> argument in

	git reset --hard <rev>
	git reset --soft <rev>

needs to be a commit to be sensible.  But in

	git reset <rev> -- <path> <path> ...

using other trees can be useful.

For example, to apply changes from a branch that has the current
branch merged as a subtree:

	git reset master:gitk-git -- .

Signed-off-by: Jonathan Nieder <jrnieder@gmail.com>
---
 builtin/reset.c  |   11 ++++++-----
 t/t7102-reset.sh |   31 +++++++++++++++++++++++++++++++
 2 files changed, 37 insertions(+), 5 deletions(-)

diff --git a/builtin/reset.c b/builtin/reset.c
index a52e6f8..2375472 100644
--- a/builtin/reset.c
+++ b/builtin/reset.c
@@ -306,15 +306,10 @@ int cmd_reset(int argc, const char **argv, const char *prefix)
 	}
 
 	if (get_sha1(rev, sha1))
 		die("Failed to resolve '%s' as a valid ref.", rev);
 
-	commit = lookup_commit_reference(sha1);
-	if (!commit)
-		die("Could not parse object '%s'.", rev);
-	hashcpy(sha1, commit->object.sha1);
-
 	/* git reset tree [--] paths... can be used to
 	 * load chosen paths from the tree into the index without
 	 * affecting the working tree nor HEAD. */
 	if (i < argc) {
 		if (reset_type == MIXED)
@@ -323,10 +318,16 @@ int cmd_reset(int argc, const char **argv, const char *prefix)
 			die("Cannot do %s reset with paths.",
 					reset_type_names[reset_type]);
 		return read_from_tree(prefix, argv + i, sha1,
 				quiet ? REFRESH_QUIET : REFRESH_IN_PORCELAIN);
 	}
+
+	commit = lookup_commit_reference(sha1);
+	if (!commit)
+		die("Could not parse object '%s'.", rev);
+	hashcpy(sha1, commit->object.sha1);
+
 	if (reset_type == NONE)
 		reset_type = MIXED; /* by default */
 
 	if (reset_type != SOFT && reset_type != MIXED)
 		setup_work_tree();
diff --git a/t/t7102-reset.sh b/t/t7102-reset.sh
index b8cf260..3e95da3 100755
--- a/t/t7102-reset.sh
+++ b/t/t7102-reset.sh
@@ -7,10 +7,18 @@ test_description='git reset
 
 Documented tests for git reset'
 
 . ./test-lib.sh
 
+test_exit_code () {
+	echo $1 >expect.code &&
+	shift &&
+	"$@"
+	echo $? >actual.code &&
+	test_cmp expect.code actual.code
+}
+
 test_expect_success 'creating initial files and commits' '
 	test_tick &&
 	echo "1st file" >first &&
 	git add first &&
 	git commit -m "create 1st file" &&
@@ -409,17 +417,40 @@ test_expect_success 'test resetting the index at give paths' '
 	test_must_fail git diff-index --cached --exit-code "$T" &&
 	test "$T" != "$U"
 
 '
 
+test_expect_success 'reset modified path from tree' '
+	echo hello >other &&
+	git reset --hard &&
+	git add other &&
+	T=$(git write-tree) &&
+	git rm -f other &&
+	test_exit_code 1 git reset $T other &&
+	git diff-index --cached --exit-code "$T"
+'
+
+test_expect_success 'try to reset from blob' '
+	git reset --hard &&
+	B=$(git rev-parse --verify HEAD:file1) &&
+	test_exit_code 128 git reset $B -- .
+'
+
 test_expect_success 'resetting an unmodified path is a no-op' '
 	git reset --hard &&
 	git reset -- file1 &&
 	git diff-files --exit-code &&
 	git diff-index --cached --exit-code HEAD
 '
 
+test_expect_success 'reset unmodified path from tree' '
+	git reset --hard &&
+	git reset HEAD^{tree} -- file1 &&
+	git diff-files --exit-code &&
+	git diff-index --cached --exit-code HEAD
+'
+
 cat > expect << EOF
 Unstaged changes after reset:
 M	file2
 EOF
 
-- 
1.7.2.3

[PATCH 3/4] reset: accept "git reset -- <path>" from unborn branch

[Jonathan Nieder]

A common workflow:

	git checkout <branch>
	... hack hack hack ...
	git add -- <path1> <path2>
	git reset -- <path1>; # oops, that one isn't ready yet
	git commit

One might try to use 'git reset' to undo the effect of 'git add' on an
unborn branch, too, but it doesn't work:

	... hack hack hack ...
	$ git add -- <path1> <path2>
	$ git reset -- <path1>
	fatal: Failed to resolve 'HEAD' as a valid ref.

It is obvious that the operator meant to remove the entry for <path1>,
so just do that.

This patch only affects the "git reset <path>" syntax; explicit
use of "git reset HEAD <path>" will still error out.

Suggested-by: Sverre Rabbelier <srabbelier@gmail.com>
Signed-off-by: Jonathan Nieder <jrnieder@gmail.com>
---
 builtin/reset.c         |   15 ++++++++++++-
 t/t7106-reset-unborn.sh |   50 +++++++++++++++++++++++++++++++++++++++++++++++
 2 files changed, 63 insertions(+), 2 deletions(-)
 create mode 100755 t/t7106-reset-unborn.sh

diff --git a/builtin/reset.c b/builtin/reset.c
index 2375472..ff57764 100644
--- a/builtin/reset.c
+++ b/builtin/reset.c
@@ -234,12 +234,14 @@ static void die_if_unmerged_cache(int reset_type)
 }
 
 int cmd_reset(int argc, const char **argv, const char *prefix)
 {
 	int i = 0, reset_type = NONE, update_ref_status = 0, quiet = 0;
+	int unborn_branch = 0;
 	int patch_mode = 0;
-	const char *rev = "HEAD";
+	const char *implicit_HEAD = "HEAD";
+	const char *rev = implicit_HEAD;
 	unsigned char sha1[20], *orig = NULL, sha1_orig[20],
 				*old_orig = NULL, sha1_old_orig[20];
 	struct commit *commit;
 	char *reflog_action, msg[1024];
 	const struct option options[] = {
@@ -303,11 +305,18 @@ int cmd_reset(int argc, const char **argv, const char *prefix)
 		if (reset_type != NONE)
 			die("--patch is incompatible with --{hard,mixed,soft}");
 		return interactive_reset(rev, argv + i, prefix);
 	}
 
-	if (get_sha1(rev, sha1))
+	if (rev == implicit_HEAD) {
+		/* We may be on a branch yet to be born. */
+		resolve_ref("HEAD", sha1, 0, NULL);
+		if (is_null_sha1(sha1)) {
+			unborn_branch = 1;
+			hashcpy(sha1, (const unsigned char *) EMPTY_TREE_SHA1_BIN);
+		}
+	} else if (get_sha1(rev, sha1))
 		die("Failed to resolve '%s' as a valid ref.", rev);
 
 	/* git reset tree [--] paths... can be used to
 	 * load chosen paths from the tree into the index without
 	 * affecting the working tree nor HEAD. */
@@ -319,10 +328,12 @@ int cmd_reset(int argc, const char **argv, const char *prefix)
 					reset_type_names[reset_type]);
 		return read_from_tree(prefix, argv + i, sha1,
 				quiet ? REFRESH_QUIET : REFRESH_IN_PORCELAIN);
 	}
 
+	if (unborn_branch)
+		die("Failed to resolve 'HEAD' as a valid ref.");
 	commit = lookup_commit_reference(sha1);
 	if (!commit)
 		die("Could not parse object '%s'.", rev);
 	hashcpy(sha1, commit->object.sha1);
 
diff --git a/t/t7106-reset-unborn.sh b/t/t7106-reset-unborn.sh
new file mode 100755
index 0000000..7baaffd
--- /dev/null
+++ b/t/t7106-reset-unborn.sh
@@ -0,0 +1,50 @@
+#!/bin/sh
+
+test_description='git reset from a branch yet to be born'
+. ./test-lib.sh
+
+>empty
+
+index_is_empty () {
+	git ls-files >actual &&
+	test_cmp empty actual
+}
+
+test_expect_success 'reset to remove file' '
+	echo one >file &&
+	git add file &&
+	git reset file &&
+	index_is_empty
+'
+
+test_expect_success 'reset after rm to remove file' '
+	echo one >file &&
+	git add file &&
+	rm file &&
+	git reset -- file &&
+	index_is_empty
+'
+
+test_expect_success 'reset file that does not match index' '
+	echo one >file &&
+	git add file &&
+	echo two >file &&
+	git reset -- file &&
+	index_is_empty
+'
+
+test_expect_success 'reset absent file' '
+	git reset -- file &&
+	index_is_empty
+'
+
+test_expect_success 'reset HEAD <files> from unborn branch' '
+	test_must_fail git reset HEAD -- .
+'
+
+test_expect_success 'reset HEAD from unborn branch' '
+	test_must_fail git reset HEAD &&
+	test_must_fail git reset HEAD --
+'
+
+test_done
-- 
1.7.2.3

[PATCH 4/4] reset: accept "git reset HEAD <path>" from unborn branch

[Jonathan Nieder]

If I try:

	... hack hack hack ...
	git add .
	rm <path1>; # bad file!
	git reset <path1>

git will respond by informing me that this use of <path1> is
ambiguous.  So I might try to disambiguate:

	git reset HEAD <path1>

This works when HEAD represents a branch, but not in the 'new
repository' ('branch yet to be born') case.

Even in the unborn branch case, it is clear what the operator meant
to do (namely, remove the entry for <path1>), so do that.

Signed-off-by: Jonathan Nieder <jrnieder@gmail.com>
---
 builtin/reset.c         |    5 ++---
 t/t7106-reset-unborn.sh |    5 ++++-
 2 files changed, 6 insertions(+), 4 deletions(-)

diff --git a/builtin/reset.c b/builtin/reset.c
index ff57764..d9a5702 100644
--- a/builtin/reset.c
+++ b/builtin/reset.c
@@ -236,12 +236,11 @@ static void die_if_unmerged_cache(int reset_type)
 int cmd_reset(int argc, const char **argv, const char *prefix)
 {
 	int i = 0, reset_type = NONE, update_ref_status = 0, quiet = 0;
 	int unborn_branch = 0;
 	int patch_mode = 0;
-	const char *implicit_HEAD = "HEAD";
-	const char *rev = implicit_HEAD;
+	const char *rev = "HEAD";
 	unsigned char sha1[20], *orig = NULL, sha1_orig[20],
 				*old_orig = NULL, sha1_old_orig[20];
 	struct commit *commit;
 	char *reflog_action, msg[1024];
 	const struct option options[] = {
@@ -305,11 +304,11 @@ int cmd_reset(int argc, const char **argv, const char *prefix)
 		if (reset_type != NONE)
 			die("--patch is incompatible with --{hard,mixed,soft}");
 		return interactive_reset(rev, argv + i, prefix);
 	}
 
-	if (rev == implicit_HEAD) {
+	if (!strcmp(rev, "HEAD")) {
 		/* We may be on a branch yet to be born. */
 		resolve_ref("HEAD", sha1, 0, NULL);
 		if (is_null_sha1(sha1)) {
 			unborn_branch = 1;
 			hashcpy(sha1, (const unsigned char *) EMPTY_TREE_SHA1_BIN);
diff --git a/t/t7106-reset-unborn.sh b/t/t7106-reset-unborn.sh
index 7baaffd..c03f309 100755
--- a/t/t7106-reset-unborn.sh
+++ b/t/t7106-reset-unborn.sh
@@ -37,11 +37,14 @@ test_expect_success 'reset absent file' '
 	git reset -- file &&
 	index_is_empty
 '
 
 test_expect_success 'reset HEAD <files> from unborn branch' '
-	test_must_fail git reset HEAD -- .
+	echo one >file &&
+	git add file &&
+	git reset HEAD -- . &&
+	index_is_empty
 '
 
 test_expect_success 'reset HEAD from unborn branch' '
 	test_must_fail git reset HEAD &&
 	test_must_fail git reset HEAD --
-- 
1.7.2.3

Re: [RFC/PATCH] reset: accept "git reset <removed file>"

[Jonathan Nieder]

Junio C Hamano wrote:

> It is generally unsafe, I am afraid, and that is one of the reasons why
> verify_filename() does not look in the index (the other one was "it is
> merely a safety measure based on heuristics to help users, and no point
> spending extra code nor cycles", iow, deliberate laziness ;-)), making the
> proposal of this patch under discussion somewhat iffy.

Let's drop it, then.  I'll continue the practice of always including "--"
in examples suggested to new users.

Re: [PATCH 4/4] reset: accept "git reset HEAD <path>" from unborn branch

[Junio C Hamano]

Jonathan Nieder <jrnieder@gmail.com> writes:

> If I try:
>
> 	... hack hack hack ...
> 	git add .
> 	rm <path1>; # bad file!
> 	git reset <path1>
>
> git will respond by informing me that this use of <path1> is
> ambiguous.

Which is fixed by 3/4.  I think that is probably a sane thing to do.

> ...  So I might try to disambiguate:
>
> 	git reset HEAD <path1>

I however do not think this is sane, as you are _explicitly_ referring to
HEAD, saying "I want to pull this out of the commit pointed by the HEAD",
while there is _no such commit_.  Sounds somewhat insane.

But why is path1 ambiguous in the first place?  It is because it is not
considered to be a pathname, and it is not a valid refname either, right?

Didn't we discuss a separate topic to teach verify_filename/non_filename
to optionally look into the index?  If we did that, perhaps we do not even
need 3/4, no?

We could make it the caller's responsibility to run read_cache() before
calling these two functions (verify_filename() and verify_non_filename()
will just use active_cache[] without reading the index themselves).
Alternatively, we could add a new option "use_index" (0: do not use index
at all, 1: run read_cache() to the_index and use it for checking, 2: run
read_index() on a temporary in-core index, use it for checking and then
discard the temporary in-core index to keep them free of side-effect) to
them.  I haven't looked at all the call sites of them to see which one is
better, though.

Re: [PATCH 4/4] reset: accept "git reset HEAD <path>" from unborn branch

[Jonathan Nieder]

Junio C Hamano wrote:
> Jonathan Nieder <jrnieder@gmail.com> writes:

>> 	git add .
>> 	rm <path1>; # bad file!
>> 	git reset <path1>
>>
>> git will respond by informing me that this use of <path1> is
>> ambiguous.
>
> Which is fixed by 3/4.

No, I didn't fix that.

What 3/4 allows is

	git reset -- <path1>

The explicit "--" is required in the case where that file is not
present on disk.

>> ...  So I might try to disambiguate:
>>
>> 	git reset HEAD <path1>
>
> I however do not think this is sane, as you are _explicitly_ referring to
> HEAD, saying "I want to pull this out of the commit pointed by the HEAD",
> while there is _no such commit_.  Sounds somewhat insane.

Yes, makes sense.  I started out thinking of HEAD as a sort of
abstract symbol (like the occasionally-proposed INDEX) but it probably
is better to get used to it just being a reference early on.

> But why is path1 ambiguous in the first place?  It is because it is not
> considered to be a pathname, and it is not a valid refname either, right?
>
> Didn't we discuss a separate topic to teach verify_filename/non_filename
> to optionally look into the index?  If we did that, perhaps we do not even
> need 3/4, no?

That would eliminate the need for 4/4, I think.  Thanks for the pointers.

Re: Git terminology: remote, add, track, stage, etc.

[Thore Husfeldt]

On 18 Oct 2010, at 23:41, Matthieu Moy wrote:

> We already came up with a better wording, namely "upstream", and used
> in in "git push --set-upstream". Probably a next step would be to
> deprecate any other occurence of --track meaning the same thing (git
> checkout --track seems to me to be a candidate, git branch has both
> --track and --set-upstream). One difficulty is to do that with
> backward compatibility in mind.

I’ve tried to play around with this concept now, *in casu* by trying to edit the Pro Git source.

I’m not sure we all agree on what is what, so let me try to clarify.

In the following, Alice has bobsstuff, bob/master, and (Bob’s) master, which she got from

> alice% git checkout --track -b bobsstuff bob/master

(Or using `git branch`). Git tells her that

> Branch bobsstuff set up to track remote branch master from bob.

(By the way, I think “remote branch” is useful and correct, here.)

Let me see if I can use the proposed terminology:

1. bob/master *tracks* master.
2. bob/master is a remote-tracking branch
3. master is a remote branch
4. bob/master has been marked as "upstream" from bobsstuff 

Is master upstream from bobbstuff as well? The man page of `git branch` seems to think so:

> Furthermore, it directs git pull without arguments to pull from the upstream when the new branch is checked out.

So both bob/master and master are sometimes called "upstream", and both bobsstuff and bob/master are sometimes called "tracking".

Let‘s try to look at the relevant Pro Git section, to get a feeling for how this terminology work when you actually try to explain something well:
> 
> ### Tracking Branches ###
> 
> Checking out a local branch from a remote branch automatically creates what is called a _tracking branch_. Tracking branches are local branches that have a direct relationship to a remote branch. If you’re on a tracking branch and type git push, Git automatically knows which server and branch to push to. Also, running `git pull` while on one of these branches fetches all the remote references and then automatically merges in the corresponding remote branch.
> 
> When you clone a repository, it generally automatically creates a `master` branch that tracks `origin/master`. That’s why `git push` and `git pull` work out of the box with no other arguments. However, you can set up other tracking branches if you wish — ones that don’t track branches on `origin` and don’t track the `master` branch. The simple case is the example you just saw, running `git checkout -b [branch] [remotename]/[branch]`. If you have Git version 1.6.2 or later, you can also use the `--track` shorthand:

This is a good section, and explains a lot. But, as with much of the Git documentation, the terminology is undisciplined. Take “tracking branches”. The section is about refs like bobbstuff, which is no longer called tracking, but “a branch that has been configured to set up an upstream relation”. Currently, if I understand the proposed terminology, there is no word for what the Pro Git book calls “tracking branches.” (I’d be happy to be wrong about this.)

Let me try

> ### Upstream branches ###
> 
> A local branch can be set up in a direct relationship to a remote branch; we say the that the remote branch is _upstream_. In this configuration, if you type `git push`, Git automatically knows which server and branch to push to. Also, running `git pull` on one of these branches fetches all the remote references and then automatically merges in the corresponding remote branch.
> 
> When you clone a repository, Git automatically creates a `master` branch whose upstream branch is the remote-tracking branch `origin/master`.

This is not really good, because the immediately preceding section is about “remote-tracking branches” (currently called “remote branches”, by the way). And “remote-tracking branches” and “upstream branches” are the same – they both refer to bob/master, but from different perspectives. Now there are two sections about bob/master, yet the conceptually interesting branches are bobsstuff (sometimes called the “tracking branch”) and master (sometimes called the “remote branch”). bob/master is just an elegant implementation that facilitates the communication between these two branches. (This is not impossible to fix with a good rewrite.)

I’d be really happy to rewrite the documentation about this stuff (including submitting a patch to Pro Git and other useful references), but my enthusiasm is tempered by a nagging suspicion that the full terminological effect of no longer having a word for the kind of branch that bobsstuff is has been fully realised. 

Re: Git terminology: remote, add, track, stage, etc.

[Matthieu Moy]

Thore Husfeldt <thore.husfeldt@gmail.com> writes:

>> Branch bobsstuff set up to track remote branch master from bob.
>
> (By the way, I think “remote branch” is useful and correct, here.)

But "track" should be "upstream" here to be consistant with
"--set-upstream". Maybe:

Remote branch master from bob set as upstream for bobsstuff.

?

> Let me see if I can use the proposed terminology:
>
> 1. bob/master *tracks* master.
> 2. bob/master is a remote-tracking branch

I do like the dash between remote and tracking.

This is roughly the current terminology, but as you pointed out, it's
not used consistantly in the doc.

> 3. master is a remote branch
> 4. bob/master has been marked as "upstream" from bobsstuff 

That's my understanding too.

(no time for more detailed answer, sorry)

-- 
Matthieu Moy
http://www-verimag.imag.fr/~moy/

Re: Git terminology: remote, add, track, stage, etc.

[Drew Northup]

On Wed, 2010-10-20 at 13:34 +0200, Matthieu Moy wrote:
> Thore Husfeldt <thore.husfeldt@gmail.com> writes:

> > Let me see if I can use the proposed terminology:
> >
> > 1. bob/master *tracks* master.
> > 2. bob/master is a remote-tracking branch
> 
> I do like the dash between remote and tracking.
> 
> This is roughly the current terminology, but as you pointed out, it's
> not used consistantly in the doc.

The only way in which "tracking" is not consistent is in that many
people seem to be insisting that one cannot apply the idiom of tracking
to ALL kinds of tracking that git does. Git tracks changes in CONTENT.
It matters not where that content is. It does not track files, branches,
nor repositories--those are mere containers of CONTENT that git tracks
the changes of.
Perhaps we need to make this more explicit in the documentation?

-- 
-Drew Northup
________________________________________________
"As opposed to vegetable or mineral error?"
-John Pescatore, SANS NewsBites Vol. 12 Num. 59

Re: Git terminology: remote, add, track, stage, etc.

[Michael Haggerty]

On 10/18/2010 11:57 PM, Jakub Narebski wrote:
> Well, there is different suggestion: make `git stage`, `git track` and
> `git mark-resolved` to be *specializations* of `git add`, with added
> safety checks: 'git stage' would work only on files known to git /
> under version control already, 'git track' would work only on
> untracked files (and do what 'git add -N' does), and 'git mark-resolved'
> would work only on files which were part of a merge conflict.

I think that is a great idea.  The thing that I found most confusing
when learning git is that variations on a single command often have very
different effects.  My pet peeve is the over-versatile "git checkout":

git checkout BRANCH : Check out a branch.  This is the functionality
that I would expect from a "checkout" command.

git checkout -b NEWBRANCH OLDBRANCH : For me this was unintuitive,
because (IMO) the main effect of the command is to create a new branch.
 (I consider that more significant than the checkout because it has a
persistent effect on the repository.)  Therefore, I would expect this
functionality to be provided by "git branch" (something like "git branch
--checkout NEWBRANCH OLDBRANCH").

git checkout -b NEWBRANCH : This is even more unintuitive, because no
content is being checked out at all.  This should be written "git branch
--checkout NEWBRANCH".

git checkout -- PATH : To me this is again a totally different
operation.  The other uses of "git checkout" are safe; they don't lose
any information.  But this usage discards the working copy changes
irretrievably.  Such a different operation deserves a different command
with a "dangerous-sounding" name.  I think this functionality should be
made more easily accessible via "git reset", as has been suggested
elsewhere on this thread.  (Unfortunately "git revert" is already taken.)

git checkout BRANCH -- PATH : This is even more perverse.  Usually
"check out" makes the working copy more similar to a version in the
repository.  But this command makes it more different.

Michael

-- 
Michael Haggerty
mhagger@alum.mit.edu
http://softwareswirl.blogspot.com/

Re: Git terminology: remote, add, track, stage, etc.

[Drew Northup]

On Thu, 2010-10-21 at 10:44 +0200, Michael Haggerty wrote:
> On 10/18/2010 11:57 PM, Jakub Narebski wrote:
> > Well, there is different suggestion: make `git stage`, `git track` and
> > `git mark-resolved` to be *specializations* of `git add`, with added
> > safety checks: 'git stage' would work only on files known to git /
> > under version control already, 'git track' would work only on
> > untracked files (and do what 'git add -N' does), and 'git mark-resolved'
> > would work only on files which were part of a merge conflict.
> 
> I think that is a great idea.  The thing that I found most confusing
> when learning git is that variations on a single command often have very
> different effects.  

Ok, so what will "git stage" do when a change of a file is already
staged and it is executed again (on new changes)? The point of "git add"
is that it is adding the current state to the index, not that it is
adding a file to version control (in contrast to most other VCS/SCM).
Adding a "git stage" that acts as if "git add" permanently adds a file
to version control merely confuses this issue in my opinion.

(Comments about checkout will come in another message, granted I come up
with the time to write them down...)

-- 
-Drew Northup
________________________________________________
"As opposed to vegetable or mineral error?"
-John Pescatore, SANS NewsBites Vol. 12 Num. 59

Re: Git terminology: remote, add, track, stage, etc.

[Thore Husfeldt]

On 21 Oct 2010, at 13:20, Drew Northup wrote:

> Ok, so what will "git stage" do when a change of a file is already
> staged and it is executed again (on new changes)?

Presumably what it already does: nothing. But one could argue that the more public-relations minded command “git stage” should give better feedback. Like so:

> $ git commit 
> $ ... edit A.txt ...
> $ git stage B.txt
> git stage: Did nothing. No uncommitted changes to stage in B.txt.
> $ git stage A.txt
> $ git stage A.txt
> git stage: Did nothing. Changes in A.txt already staged. Use `git diff --staged A.txt` to see them.

Re: Git terminology: remote, add, track, stage, etc.

[Drew Northup]

On Thu, 2010-10-21 at 14:31 +0200, Thore Husfeldt wrote:
> On 21 Oct 2010, at 13:20, Drew Northup wrote:
> 
> > Ok, so what will "git stage" do when a change of a file is already
> > staged and it is executed again (on new changes)?
> 
> Presumably what it already does: nothing. But one could argue that the more public-relations minded command “git stage” should give better feedback. Like so:
> 
> > $ git commit 
> > $ ... edit A.txt ...
> > $ git stage B.txt
> > git stage: Did nothing. No uncommitted changes to stage in B.txt.
> > $ git stage A.txt
> > $ git stage A.txt
> > git stage: Did nothing. Changes in A.txt already staged. Use `git diff --staged A.txt` to see them.

That's not what I asked.

$ git commit
$ vim A.txt
$ vim B.txt
$ git add B.txt
$ git add A.txt
$ vim B.txt
$ git add B.txt

The above sequence stages two changes on B.txt into the index.
Literally, it adds changes to git's knowledge about B.txt twice, but
does not yet commit any of it permanently to the object store.

Presumably, assuming that A.txt and B.txt did not yet exist, you are
suggesting the following command sequence:

$ git commit
$ vim A.txt
$ vim B.txt
$ git add B.txt
$ git add A.txt
$ vim B.txt
$ git stage B.txt
$ vim B.txt
$ git stage B.txt

This assumes that git SHOULD act like subversion, and I argue that there
is no reason that it should. What happens if we continue as follows:

$ vim A.txt
$ git stage A.txt
$ git commit
$ vim C.txt
$ vim A.txt
$ git stage A.txt
$ git stage C.txt

Should the last two commands fail? The earlier discussion seems to
suggest that they should. My point is that this does not seem to me to
be a useful extension of the idiom. If anything, it seems to confuse the
matter. Now, if "git stage" were an outright replacement for "git add"
there might be more use (but I'd still not be happy about the corruption
of the idiom).

-- 
-Drew Northup
________________________________________________
"As opposed to vegetable or mineral error?"
-John Pescatore, SANS NewsBites Vol. 12 Num. 59

Re: Git terminology: remote, add, track, stage, etc.

[Thore Husfeldt]

On 21 Oct 2010, at 14:56, Drew Northup wrote:

> That's not what I asked.
> [... good, concrete example omitted...]
> 
> $ vim A.txt
> $ git stage A.txt
> $ git commit
> $ vim C.txt
> $ vim A.txt
> $ git stage A.txt
> $ git stage C.txt
> 
> Should the last two commands fail?

No, not for me. (Is this in reaction to Jakub’s suggestion that an “untracked file”, like C.txt, cannot be staged before explicitly tracked?)

Maybe this is what should happen:

$ git stage C.txt
git stage: Contents of previously untracked file C.txt staged for next commit

> Now, if "git stage" were an outright replacement for "git add"
> there might be more use (but I'd still not be happy about the corruption
> of the idiom).

I tend to agree. But look at, e.g., Figure 2.1 in the Pro Git book http://progit.org/book/ch2-2.html . That view strongly enforces that something special happens to the new “pink” file, different from what happens to a “yellow” file. After this helpful discussion, I don’t like figure 2.1 so much anymore. A red arrow should go from “pink” to “blue” with text “stage the file”.

Re: Git terminology: remote, add, track, stage, etc.

[Drew Northup]

On Thu, 2010-10-21 at 16:06 +0200, Thore Husfeldt wrote:
> On 21 Oct 2010, at 14:56, Drew Northup wrote:
> 
> > That's not what I asked.
> > [... good, concrete example omitted...]
> > 
> > $ vim A.txt
> > $ git stage A.txt
> > $ git commit
> > $ vim C.txt
> > $ vim A.txt
> > $ git stage A.txt
> > $ git stage C.txt
> > 
> > Should the last two commands fail?
> 
> No, not for me. (Is this in reaction to Jakub’s suggestion that an
> “untracked file”, like C.txt, cannot be staged before explicitly
> tracked?)

I hadn't read any of his comments to mean that, but I could be missing
something...
More than anything else I was trying to feel out possible workflow
issues. A lot of people are going to (continue? to) confuse "git add"
and "svn add" if we don't make very explicit what we are up to. As you
are not suggesting we outright replace "git add" I wanted to be very
sure as to what you mean to do.

> Maybe this is what should happen:
> 
> $ git stage C.txt
> git stage: Contents of previously untracked file C.txt staged for next commit

This is reasonable. I would probably say "...untracked file C.txt added
to index and staged for next commit" to emphasize the existing "git add"
idiom, but that may be superfluous.

> > Now, if "git stage" were an outright replacement for "git add"
> > there might be more use (but I'd still not be happy about the corruption
> > of the idiom).
> 
> I tend to agree. But look at, e.g., Figure 2.1 in the Pro Git book
> http://progit.org/book/ch2-2.html . That view strongly enforces that
> something special happens to the new “pink” file, different from what
> happens to a “yellow” file. After this helpful discussion, I don’t
> like figure 2.1 so much anymore. A red arrow should go from “pink” to
> “blue” with text “stage the file”.

I can see why this would get your attention. I have to admit I ignored
it because it didn't match-up with the bulk of documentation in any way
I had yet made sense of. Once I had made sense of the idiom and looked
back at the graphic I shrugged and wondered why the author had chosen to
illustrate it that way.

-- 
-Drew Northup N1XIM
   AKA RvnPhnx on OPN
________________________________________________
"As opposed to vegetable or mineral error?"
-John Pescatore, SANS NewsBites Vol. 12 Num. 59

Re: Git terminology: remote, add, track, stage, etc.

[Miles Bader]

Drew Northup <drew.northup@maine.edu> writes:
> Ok, so what will "git stage" do when a change of a file is already
> staged and it is executed again (on new changes)?

It stages the newly updated file?

This seems entirely obvious and intuitive, far more so than "git add"...

-Miles

-- 
Happiness, n. An agreeable sensation arising from contemplating the misery of
another.

Re: Git terminology: remote, add, track, stage, etc.

[Drew Northup]

On Fri, 2010-10-22 at 13:07 +0900, Miles Bader wrote:
> Drew Northup <drew.northup@maine.edu> writes:
> > Ok, so what will "git stage" do when a change of a file is already
> > staged and it is executed again (on new changes)?
> 
> It stages the newly updated file?
> 
> This seems entirely obvious and intuitive, far more so than "git add"...

Whether "git add" or "git stage" makes any sense (or either one more
than the other) depends on the user having some specific knowledge of
how VCS/SCM works and in particular some knowledge specific to git. For
me, "git add" was virtually automatic having had some exposure to CVS
and SVN (thankfully CVS only in the past!). Once I got to the part of
the instructions where it was made clear that git does not PERPETUALLY
AND AUTOMATICALLY CAPTURE the state of CONTENT known to it the idiom of
"git add" working to ADD THE CURRENT STATE of content in a file made
perfect sense to me.
The idiom of "git stage" is likewise. One must understand that in git
all changes must be staged to the index manually before they can be
acted upon in a commit.
Neither one is particularly obvious to somebody who hasn't attempted to
understand how git works yet--just as the traffic concept of
right-of-way oft befuddles teenagers as if they were martians visiting
Times Square.

What I was asking, specifically, was how "git stage" was to act in the
given scenario. In particular I wanted to make sure that the workflow of
"make known to git, modify, add/stage changes to index, <repeat previous
two if needed>, commit, etc." did not change to include some sort of
PERPETUAL AUTOMATIC TRACKING as done with CVS/SVN (and frankly at times
a rather annoying prospect). Obviously I could not just ask that
outright and expect to get some idea of what my interlocutor was
thinking and how he internally conceived the idiom as well as an answer
to the direct question at hand.

How's that for a long answer to a seemingly simple question?

-- 
-Drew Northup N1XIM
   AKA RvnPhnx on OPN
________________________________________________
"As opposed to vegetable or mineral error?"
-John Pescatore, SANS NewsBites Vol. 12 Num. 59

Re: Git terminology: remote, add, track, stage, etc.

[Paul Bolle]

On Tue, 2010-10-19 at 11:09 -0400, Eugene Sajine wrote:
> There should be some different consistent and not inter-crossing
> naming for the origin's master branch (on the remote side), for the
> local origin/master and for local master that is a tracking branch.
> The only way i found so far to explain this is actually via the naming
> syntax where having / in the name of the branch means remote branch. I
> was a bit surprised that i can create a local branch with a slash in
> the name - probably it should be prohibited.

Allowing local branches with a slash in their name is a feature I use
heavily. Ie, in general my local repositories use this scheme:

$ git branch
* master
  $BRANCH_F00
  $USER/$TOPIC_FOO
  $USER/$TOPIC_BAR
  [...]
  $USER/$TOPIC_BAZ

This makes it trivial to quickly distinguish my (local) work from other
people's (remote) work. Does the benefit of naming clarity justify
prohibiting that scheme?


Paul Bolle

Re: Git terminology: remote, add, track, stage, etc.

[Eugene Sajine]

On Fri, Oct 22, 2010 at 4:16 PM, Paul Bolle <pebolle@tiscali.nl> wrote:
> On Tue, 2010-10-19 at 11:09 -0400, Eugene Sajine wrote:
>> There should be some different consistent and not inter-crossing
>> naming for the origin's master branch (on the remote side), for the
>> local origin/master and for local master that is a tracking branch.
>> The only way i found so far to explain this is actually via the naming
>> syntax where having / in the name of the branch means remote branch. I
>> was a bit surprised that i can create a local branch with a slash in
>> the name - probably it should be prohibited.
>
> Allowing local branches with a slash in their name is a feature I use
> heavily. Ie, in general my local repositories use this scheme:
>
> $ git branch
> * master
>  $BRANCH_F00
>  $USER/$TOPIC_FOO
>  $USER/$TOPIC_BAR
>  [...]
>  $USER/$TOPIC_BAZ
>
> This makes it trivial to quickly distinguish my (local) work from other
> people's (remote) work. Does the benefit of naming clarity justify
> prohibiting that scheme?
>
>
> Paul Bolle
>
>

Well, my approach is to use:
master - local
mybranch - local

remote from user
$ git remote add jdoe ~jdoe/project/.git

Then remote-tracking branches will be
jdoe/master
jdoe/featurex

my local branches tracking remote-tracking branches (automatic push, pull)
jd_master
jd_featurex

in this case there is no confusion between jdoe/master that is a
remote-tracking branch checkout to which will lead to detached HEAD
state and jd_master that is a local branch.

As in this syntax the slash is that meaningful, i think that reserving
this syntax "remote/branch" to the remote-tracking branches only makes
sense.

Thanks,
Eugene

Re: Git terminology: remote, add, track, stage, etc.

[Drew Northup]

On Fri, 2010-10-22 at 17:00 -0400, Eugene Sajine wrote:
> On Fri, Oct 22, 2010 at 4:16 PM, Paul Bolle <pebolle@tiscali.nl> wrote:
> > On Tue, 2010-10-19 at 11:09 -0400, Eugene Sajine wrote:
> >> There should be some different consistent and not inter-crossing
> >> naming for the origin's master branch (on the remote side), for the
> >> local origin/master and for local master that is a tracking branch.
> >> The only way i found so far to explain this is actually via the naming
> >> syntax where having / in the name of the branch means remote branch. I
> >> was a bit surprised that i can create a local branch with a slash in
> >> the name - probably it should be prohibited.
> >
> > Allowing local branches with a slash in their name is a feature I use
> > heavily. Ie, in general my local repositories use this scheme:
> >
> > $ git branch
> > * master
> >  $BRANCH_F00
> >  $USER/$TOPIC_FOO
> >  $USER/$TOPIC_BAR
> >  [...]
> >  $USER/$TOPIC_BAZ
> >
> > This makes it trivial to quickly distinguish my (local) work from other
> > people's (remote) work. Does the benefit of naming clarity justify
> > prohibiting that scheme?
> >
> >
> > Paul Bolle
> >
> >
> 
> Well, my approach is to use:
> master - local
> mybranch - local
> 
> remote from user
> $ git remote add jdoe ~jdoe/project/.git
> 
> Then remote-tracking branches will be
> jdoe/master
> jdoe/featurex
> 
> my local branches tracking remote-tracking branches (automatic push, pull)
> jd_master
> jd_featurex
> 
> in this case there is no confusion between jdoe/master that is a
> remote-tracking branch checkout to which will lead to detached HEAD
> state and jd_master that is a local branch.
> 
> As in this syntax the slash is that meaningful, i think that reserving
> this syntax "remote/branch" to the remote-tracking branches only makes
> sense.

I think that leaving it as is, wherein the "/" is not a special
character that SPECIFICALLY means remote is just fine. If people choose
to use that by convention that's dandy as well, but I don't see any
point in forcing it.

-- 
-Drew Northup N1XIM
   AKA RvnPhnx on OPN
________________________________________________
"As opposed to vegetable or mineral error?"
-John Pescatore, SANS NewsBites Vol. 12 Num. 59

Re: [PATCH v3] Porcelain scripts: Rewrite cryptic "needs update" error message

[Ramkumar Ramachandra]

Hi,

Ramkumar Ramachandra writes:
> Although Git interally has the facility to differentiate between
> porcelain and plubmbing commands and appropriately print errors,
> several shell scripts invoke plubming commands triggering cryptic
> plumbing errors to be displayed on a porcelain interface. This patch
> replaces the "needs update" message in git-pull and git-rebase, when
> `git update-index` is run, with a more friendly message.
> 
> Reported-by: Joshua Jensen <jjensen@workspacewhiz.com>
> Reported-by: Thore Husfeldt <thore.husfeldt@gmail.com>
> Signed-off-by: Ramkumar Ramachandra <artagnon@gmail.com>
> ---
>  Ref: <1285877017-8060-1-git-send-email-artagnon@gmail.com> for v2.
>  Ref: <1285514516-5112-1-git-send-email-artagnon@gmail.com> for v1.
> 
>  Thanks to Matthieu for reviewing v1 and Junio for reviewing v2: I've
>  tried to attack the problem more conservatively in this patch. It
>  doesn't list paths, and doesn't print "generic" advice.

Junio: Is this patch alright?

-- Ram

Re: Git terminology: remote, add, track, stage, etc.

[Ramkumar Ramachandra]

Hi,

Ramkumar Ramachandra writes:
> From a863e58d240956191c2fa9cbe992aaca5786730b Mon Sep 17 00:00:00 2001
> From: Ramkumar Ramachandra <artagnon@gmail.com>
> Date: Tue, 19 Oct 2010 22:42:05 +0530
> Subject: [PATCH] Documentation: Consistently use the hyphenated "remote-tracking"
> 
> Replace instances of the term "remote tracking" with "remote-tracking"
> in the documentation for clarity.
> 
> Reported-by: Thore Husfeldt <thore.husfeldt@gmail.com>
> Signed-off-by: Ramkumar Ramachandra <artagnon@gmail.com>

and

> From 7422c2af1ef40c922d8f628715ad96172e4a5734 Mon Sep 17 00:00:00 2001
> From: Ramkumar Ramachandra <artagnon@gmail.com>
> Date: Tue, 19 Oct 2010 23:16:04 +0530
> Subject: [PATCH] UI: Don't say "working directory" when we really mean "working tree"
> 
> While in some places "working directory" is used to refer to the
> (current) working directory, it's incorrectly used in places where Git
> actually means "working tree" or worktree. Weed out and replace these
> instances in the UI.
> 
> Reported-by: Thore Husfeldt <thore.husfeldt@gmail.com>
> Signed-off-by: Ramkumar Ramachandra <artagnon@gmail.com>

Junio: Are these patches suitable for inclusion?

-- Ram

Re: Git terminology: remote, add, track, stage, etc.

[Drew Northup]

On Wed, 2010-10-27 at 20:33 +0530, Ramkumar Ramachandra wrote:
> Hi,
> 
> Ramkumar Ramachandra writes:
> > From a863e58d240956191c2fa9cbe992aaca5786730b Mon Sep 17 00:00:00 2001
> > From: Ramkumar Ramachandra <artagnon@gmail.com>
> > Date: Tue, 19 Oct 2010 22:42:05 +0530
> > Subject: [PATCH] Documentation: Consistently use the hyphenated "remote-tracking"
> > 
> > Replace instances of the term "remote tracking" with "remote-tracking"
> > in the documentation for clarity.
> > 
> > Reported-by: Thore Husfeldt <thore.husfeldt@gmail.com>
> > Signed-off-by: Ramkumar Ramachandra <artagnon@gmail.com>
> 
> and
> 
> > From 7422c2af1ef40c922d8f628715ad96172e4a5734 Mon Sep 17 00:00:00 2001
> > From: Ramkumar Ramachandra <artagnon@gmail.com>
> > Date: Tue, 19 Oct 2010 23:16:04 +0530
> > Subject: [PATCH] UI: Don't say "working directory" when we really mean "working tree"
> > 
> > While in some places "working directory" is used to refer to the
> > (current) working directory, it's incorrectly used in places where Git
> > actually means "working tree" or worktree. Weed out and replace these
> > instances in the UI.
> > 
> > Reported-by: Thore Husfeldt <thore.husfeldt@gmail.com>
> > Signed-off-by: Ramkumar Ramachandra <artagnon@gmail.com>
> 
> Junio: Are these patches suitable for inclusion?
> 
> -- Ram

Ram,
Matthieu has been working on a more comprehensive set of documentation
patches--which I'm pretty sure include all of the changes you just
mentioned.


-- 
-Drew Northup N1XIM
   AKA RvnPhnx on OPN
________________________________________________
"As opposed to vegetable or mineral error?"
-John Pescatore, SANS NewsBites Vol. 12 Num. 59

Re: Git terminology: remote, add, track, stage, etc.

[Matthieu Moy]

Drew Northup <drew.northup@maine.edu> writes:

> Matthieu has been working on a more comprehensive set of documentation
> patches

Right. I had missed your patches and our works overlapped.

> --which I'm pretty sure include all of the changes you just
> mentioned.

Not all:

>> > Subject: [PATCH] Documentation: Consistently use the hyphenated "remote-tracking"

This (and other "synonyms" of remote-tracking) is addressed by my
patch, but

>> > Subject: [PATCH] UI: Don't say "working directory" when we really
>> > mean "working tree"

this isn't.

-- 
Matthieu Moy
http://www-verimag.imag.fr/~moy/

Re: Git terminology: remote, add, track, stage, etc.

[Ramkumar Ramachandra]

Hi Matthieu,

Matthieu Moy writes:
> Drew Northup <drew.northup@maine.edu> writes:
> 
> > Matthieu has been working on a more comprehensive set of documentation
> > patches
> 
> Right. I had missed your patches and our works overlapped.

Ah, I saw your huge series on the list. Looks like it needs to be
re-rolled after the reviews?

> > --which I'm pretty sure include all of the changes you just
> > mentioned.
> 
> Not all:
> 
> >> > Subject: [PATCH] Documentation: Consistently use the hyphenated "remote-tracking"
> 
> This (and other "synonyms" of remote-tracking) is addressed by my
> patch, but

Ok, we can drop this patch then- your version is more complete.

> >> > Subject: [PATCH] UI: Don't say "working directory" when we really
> >> > mean "working tree"
> 
> this isn't.

You might like to include it in your next re-roll or just leave it as
an independent patch for Junio to pick up.

-- Ram

Re: Git terminology: remote, add, track, stage, etc.

[Matthieu Moy]

Ramkumar Ramachandra <artagnon@gmail.com> writes:

>> >> > Subject: [PATCH] UI: Don't say "working directory" when we really
>> >> > mean "working tree"
>> 
>> this isn't.
>
> You might like to include it in your next re-roll or just leave it as
> an independent patch for Junio to pick up.

I'd rather keep it separate. My patch serie is already large enough
(and the patches do not really have dependancies, so we can as well
let them find their way in pu/next/master separately).

-- 
Matthieu Moy
http://www-verimag.imag.fr/~moy/

Re: [PATCH v3] Porcelain scripts: Rewrite cryptic "needs update" error message

[Junio C Hamano]

Ramkumar Ramachandra <artagnon@gmail.com> writes:

> Ramkumar Ramachandra writes:
>> Although Git interally has the facility to differentiate between
>> porcelain and plubmbing commands and appropriately print errors,
>> several shell scripts invoke plubming commands triggering cryptic
>> plumbing errors to be displayed on a porcelain interface. This patch
>> replaces the "needs update" message in git-pull and git-rebase, when
>> `git update-index` is run, with a more friendly message.
>> 
>> Reported-by: Joshua Jensen <jjensen@workspacewhiz.com>
>> Reported-by: Thore Husfeldt <thore.husfeldt@gmail.com>
>> Signed-off-by: Ramkumar Ramachandra <artagnon@gmail.com>
>> ---
>>  Ref: <1285877017-8060-1-git-send-email-artagnon@gmail.com> for v2.
>>  Ref: <1285514516-5112-1-git-send-email-artagnon@gmail.com> for v1.
>> 
>>  Thanks to Matthieu for reviewing v1 and Junio for reviewing v2: I've
>>  tried to attack the problem more conservatively in this patch. It
>>  doesn't list paths, and doesn't print "generic" advice.
>
> Junio: Is this patch alright?

I did not see anything glaringly wrong in the patch offhand.  The new
messages look a bit too verbose, though.

Will queue and see what people would say.

Re: [PATCH v3] Porcelain scripts: Rewrite cryptic "needs update" error message

[Ævar Arnfjörð Bjarmason]

On Tue, Oct 19, 2010 at 16:39, Ramkumar Ramachandra <artagnon@gmail.com> wrote:

> -               git update-index --ignore-submodules --refresh &&
> -               git diff-files --ignore-submodules --quiet &&
> -               git diff-index --ignore-submodules --cached --quiet HEAD -- ||
> -               die "refusing to pull with rebase: your working tree is not up-to-date"
> +               require_clean_work_tree "pull with rebase" "Please commit or stash them."

Doing this sort of thing is basically incompatible with doing
i18n. I'll work around this when rebasing the ab/i18n series, but in
the long term we shouldn't be doing stuff like this.