Skip to contentSkip to conversation

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

PATCH In review Thore Husfeldt 16 participants 59 messages Jun 15, 2016 Documentation

lore
Share & tools
lore
#0 lore raw

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.

#1 lore raw

Hi Thore,

Quoted 5 lines · Thore Husfeldt

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!

Quoted 4 lines

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?

Quoted 3 lines

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.

Quoted 4 lines

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

Quoted 2 lines

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?

Quoted 3 lines

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

Quoted 4 lines

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

Quoted 4 lines

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

Quoted 7 lines

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

Quoted 3 lines

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.

Quoted 3 lines

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

#2 lore raw

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

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.

---

Quoted 5 lines · Jonathan Nieder

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(-)
builtin/reset.c +7 -1
index 0037be4..7d23d75 100644
@@ -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]);
 		}
 	}
 
t/t7102-reset.sh +32 -2
index b8cf260..69d125e 100755
@@ -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
Signature · 1 line
1.7.2.3
#3 lore raw

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

Quoted 10 lines · 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

Quoted 8 lines

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.

---

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?

Quoted 8 lines
builtin/reset.c +0 -0
index 0037be4..7d23d75 100644
@@ -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 */

builtin/reset.c int cmd_reset(int argc, const char **argv, const char *prefix) · line 306

Quoted 10 lines
builtin/reset.c +7 -1
-			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.

#4 lore raw

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

Quoted 3 lines · Junio C Hamano

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?

Quoted 2 lines

- 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?

#5 lore raw

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

Quoted 13 lines · Jonathan Nieder
Quoted 3 lines · Junio C Hamano

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?

Quoted 8 lines
Quoted 2 lines

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

#6 lore raw

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

Quoted 5 lines · Junio C Hamano

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.

#7 lore raw
In reply to Thore Husfeldt

Heya,

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

Quoted 2 lines · Thore Husfeldt

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

Thanks.

Quoted 1 line

And what an annoying learning experience.

Thanks again :).

Quoted 6 lines

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!

Quoted 5 lines

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.

Quoted 4 lines

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?

Quoted 2 lines

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.

Quoted 5 lines

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?

Quoted 2 lines

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.

Quoted 7 lines

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

Quoted 8 lines

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

Quoted 2 lines

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

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

Quoted 5 lines

   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.

Quoted 3 lines

(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?

Quoted 1 line

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

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

Quoted 7 lines

   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.

Quoted 8 lines

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.

Quoted 3 lines

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'

Quoted 3 lines

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.

Quoted 9 lines

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?

Signature · 3 lines
Cheers,

Sverre Rabbelier
#8 lore raw
Quoted 8 lines · Sverre Rabbelier
Quoted 5 lines

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.

#9 lore raw
In reply to Sverre Rabbelier
Quoted 6 lines · Sverre Rabbelier
Quoted 4 lines · Thore Husfeldt

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

Quoted 8 lines

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

Quoted 2 lines

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 <[email protected]>
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.

---
 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(-)
Documentation/config.txt +1 -1
index 71ddb6c..736b22f 100644
@@ -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
Documentation/fetch-options.txt +1 -1
index 470ac31..a435c23 100644
@@ -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[]
 
Documentation/git-gc.txt +1 -1
index 315f07e..d6d6833 100644
@@ -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:
 
 ------------
Documentation/git-log.txt +1 -1
index 6d40f00..ff41784 100644
@@ -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::
Documentation/git-pull.txt +1 -1
index c50f7dc..33e8438 100644
@@ -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.
 
Documentation/git-remote.txt +2 -2
index aa021b0..3143c89 100644
@@ -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'::
Documentation/gittutorial.txt +3 -3
index 1c16066..0982f74 100644
@@ -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
Documentation/rev-list-options.txt +1 -1
index ebc0108..052e64f 100644
@@ -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::
Documentation/user-manual.txt +1 -1
index 77eb483..cc65077 100644
@@ -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:
 
Signature · 1 line
1.7.2.2.409.gdbb11.dirty
Quoted 5 lines
Quoted 3 lines

(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 <[email protected]>
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.

---
 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(-)
builtin/apply.c +1 -1
index 23c18c5..9166320 100644
@@ -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));
convert.c +2 -2
index 01de9a8..441708e 100644
@@ -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);
 		}
git-filter-branch.sh +1 -1
index 962a93b..0ab5551 100755
@@ -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
git-stash.sh +1 -1
index 7561b37..86cf24e 100755
@@ -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
setup.c +1 -1
index a3b76de..55f8fe3 100644
@@ -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;
 	}
 
unpack-trees.c +1 -1
index 803445a..a70b57c 100644
@@ -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;
 		}
 	}
wt-status.c +2 -2
index fc2438f..89831cb 100644
@@ -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)" : "");
 	}
 }
 
Signature · 1 line
1.7.2.2.409.gdbb11.dirty
Quoted 10 lines
Quoted 7 lines

   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

#10 lore raw
Quoted 2 lines · Ramkumar Ramachandra
Signature · 1 line
1.7.2.2.409.gdbb11.dirty

Please, one patch per message in the future.

Quoted 7 lines
Quoted 6 lines · Sverre Rabbelier
Quoted 1 line · Thore Husfeldt

   (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?

---

builtin/reset.c +20 -5
index 0037be4..cde103f 100644
@@ -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)
#11 lore raw
Quoted 2 lines · Jonathan Nieder

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.

builtin/reset.c int cmd_reset(int argc, const char **argv, const char *prefix) · line 303

Quoted 1 line
builtin/reset.c +1 -0
+	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.

#12 lore raw

cover reset: be more flexible about <rev>

Quoted 3 lines · Junio C Hamano

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
Signature · 1 line
1.7.2.3
#13 lore raw

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

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
---
 builtin/reset.c        |   12 ++++++------
 t/t7105-reset-patch.sh |   12 ++++++++++++
 2 files changed, 18 insertions(+), 6 deletions(-)
builtin/reset.c +6 -6
index 0037be4..a52e6f8 100644
@@ -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)
t/t7105-reset-patch.sh +12 -0
index 9891e2c..ba3ff42 100755
@@ -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
Signature · 1 line
1.7.2.3
#14 lore raw

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

In reply to 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 -- .

---
 builtin/reset.c  |   11 ++++++-----
 t/t7102-reset.sh |   31 +++++++++++++++++++++++++++++++
 2 files changed, 37 insertions(+), 5 deletions(-)
builtin/reset.c +6 -5
index a52e6f8..2375472 100644
@@ -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();
t/t7102-reset.sh +31 -0
index b8cf260..3e95da3 100755
@@ -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
 
Signature · 1 line
1.7.2.3
#15 lore raw

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

In reply to 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.

---
 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
builtin/reset.c +13 -2
index 2375472..ff57764 100644
@@ -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);
 
t/t7106-reset-unborn.sh new file +50 -0

50 lines not on this page · raw message

Signature · 1 line
1.7.2.3
#16 lore raw

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

In reply to 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.

---
 builtin/reset.c         |    5 ++---
 t/t7106-reset-unborn.sh |    5 ++++-
 2 files changed, 6 insertions(+), 4 deletions(-)
builtin/reset.c +2 -3
index ff57764..d9a5702 100644
@@ -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);
t/t7106-reset-unborn.sh +4 -1
index 7baaffd..c03f309 100755
@@ -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 --
Signature · 1 line
1.7.2.3
#17 lore raw

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

Quoted 9 lines · 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.

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

Quoted 3 lines

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

#18 lore raw

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

Quoted 10 lines · Junio C Hamano
Quoted 6 lines · Jonathan Nieder

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.

Quoted 7 lines
Quoted 3 lines

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

Quoted 6 lines

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.

#19 lore raw
In reply to Jonathan Nieder

Heya,

Quoted 2 lines · Jonathan Nieder

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!

Signature · 3 lines
Cheers,

Sverre Rabbelier
#20 lore raw

Also, in the user-manual.txt:

Quoted 21 lines

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
------------------------------------------------
Quoted 2 lines

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.

#21 lore raw

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

Quoted 1 line · Thore Husfeldt

Also, in the user-manual.txt:

[...]

Quoted 7 lines
Quoted 5 lines

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.

---

Documentation/user-manual.txt +5 -2
index 77eb483..9f82fa6 100644
@@ -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.
 
#22 lore raw

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

Documentation/user-manual.txt $ git branch -r · line 363

Quoted 4 lines · Jonathan Nieder
Documentation/user-manual.txt +2 -2
-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"?

Signature · 2 lines
Matthieu Moy
http://www-verimag.imag.fr/~moy/
#23 lore raw
In reply to Thore Husfeldt
Quoted 23 lines · Thore Husfeldt

Also, in the user-manual.txt:

Quoted 21 lines

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
------------------------------------------------
Quoted 4 lines
Quoted 2 lines

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

#24 lore raw
In reply to Ramkumar Ramachandra

Hi,

Quoted 10 lines · Ramkumar Ramachandra

From a863e58d240956191c2fa9cbe992aaca5786730b Mon Sep 17 00:00:00 2001
From: Ramkumar Ramachandra <[email protected]>
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.

and

Quoted 5 lines

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

Quoted 7 lines

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.

Junio: Are these patches suitable for inclusion?

-- Ram

#25 lore raw
Quoted 26 lines · Ramkumar Ramachandra

Hi,

Quoted 10 lines · Ramkumar Ramachandra

From a863e58d240956191c2fa9cbe992aaca5786730b Mon Sep 17 00:00:00 2001
From: Ramkumar Ramachandra <[email protected]>
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.

and

Quoted 10 lines

From 7422c2af1ef40c922d8f628715ad96172e4a5734 Mon Sep 17 00:00:00 2001
From: Ramkumar Ramachandra <[email protected]>
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.

Quoted 6 lines
Quoted 2 lines

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.

Signature · 5 lines
-Drew Northup N1XIM
   AKA RvnPhnx on OPN
________________________________________________
"As opposed to vegetable or mineral error?"
-John Pescatore, SANS NewsBites Vol. 12 Num. 59
#26 lore raw
Quoted 2 lines · Drew Northup

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

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

Quoted 2 lines

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

Not all:

Quoted 1 line
Quoted 1 line
Quoted 1 line

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

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

Quoted 2 lines
Quoted 2 lines
Quoted 2 lines

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

this isn't.

Signature · 2 lines
Matthieu Moy
http://www-verimag.imag.fr/~moy/
#27 lore raw

Hi Matthieu,

Quoted 6 lines · Matthieu Moy
Quoted 2 lines · Drew Northup

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?

Quoted 9 lines
Quoted 2 lines

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

Not all:

Quoted 1 line
Quoted 1 line
Quoted 1 line

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.

Quoted 4 lines
Quoted 2 lines
Quoted 2 lines
Quoted 2 lines

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

#28 lore raw
Quoted 7 lines · Ramkumar Ramachandra
Quoted 4 lines
Quoted 2 lines
Quoted 2 lines
Quoted 2 lines

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

Signature · 2 lines
Matthieu Moy
http://www-verimag.imag.fr/~moy/
#29 lore raw
In reply to Thore Husfeldt
Quoted 11 lines · 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.

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.

Quoted 9 lines

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.

Quoted 7 lines

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.

Quoted 7 lines

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

[...]

Quoted 5 lines

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.

Quoted 2 lines

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

[...]

Quoted 5 lines

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').

Quoted 7 lines

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.

Quoted 2 lines

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.

Quoted 3 lines

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

Quoted 2 lines

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

[...]

Quoted 8 lines

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.

Quoted 17 lines

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.

Quoted 5 lines

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.

Quoted 6 lines

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.

[...]

Quoted 8 lines

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.

Quoted 4 lines

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.

Quoted 9 lines

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.

Signature · 3 lines
Jakub Narebski
Poland
ShadeHawk on #git
#30 lore raw
Quoted 8 lines

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

Quoted 6 lines

* 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

#31 lore raw

On Tue, 19 Oct 2010, Matthijs Kooijman wrote:

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

Quoted 7 lines
Quoted 7 lines

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

Quoted 7 lines
Quoted 7 lines

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

Quoted 6 lines

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.

Quoted 6 lines

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

Quoted 4 lines

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.

Signature · 2 lines
Jakub Narebski
Poland
#32 lore raw

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

Jonathan Nieder:

Quoted 1 line

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

Quoted 1 line

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:

Quoted 1 line

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:

Quoted 2 lines

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:

Quoted 1 line
$ 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:

Quoted 1 line

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:

Quoted 1 line

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.

Quoted 1 line

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

#33 lore raw

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

Quoted 5 lines · Thore Husfeldt

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

Jonathan Nieder:

Quoted 8 lines

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.

Quoted 10 lines

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.

Quoted 3 lines

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.

Quoted 10 lines

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.

Quoted 9 lines

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:

Quoted 1 line
$ git branch -r			# list all remote branches

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

Quoted 5 lines
  $ git branch -r		# list all remote-tracking branches
Quoted 7 lines

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.

Quoted 6 lines

Matthieu again:

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

Quoted 6 lines

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.

Quoted 2 lines

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

Quoted 2 lines

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.

Quoted 5 lines

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 ;-)

Quoted 11 lines

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?

Quoted 8 lines

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:

Quoted 8 lines

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

Quoted 8 lines

??> 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?

Signature · 3 lines
Jakub Narebski
Poland
ShadeHawk on #git
#34 lore raw
In reply to Jakub Narebski
Quoted 6 lines · Jakub Narebski

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

Signature · 3 lines
Michael Haggerty
[email protected]
http://softwareswirl.blogspot.com/
#35 lore raw
Quoted 11 lines · Michael Haggerty
Quoted 6 lines · Jakub Narebski

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

Signature · 4 lines
-Drew Northup
________________________________________________
"As opposed to vegetable or mineral error?"
-John Pescatore, SANS NewsBites Vol. 12 Num. 59
#36 lore raw
Quoted 2 lines · Drew Northup

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:

Quoted 7 lines
$ 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.
#37 lore raw
Quoted 14 lines · Thore Husfeldt
Quoted 2 lines · Drew Northup

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:

Quoted 7 lines
$ 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).

Signature · 4 lines
-Drew Northup
________________________________________________
"As opposed to vegetable or mineral error?"
-John Pescatore, SANS NewsBites Vol. 12 Num. 59
#38 lore raw
Quoted 11 lines · Drew Northup

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
Quoted 1 line

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
Quoted 3 lines

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

#39 lore raw
Quoted 13 lines · Thore Husfeldt
Quoted 11 lines · Drew Northup

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
Quoted 5 lines
Quoted 1 line

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.

Quoted 4 lines

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.

Quoted 10 lines
Quoted 3 lines

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.

Signature · 5 lines
-Drew Northup N1XIM
   AKA RvnPhnx on OPN
________________________________________________
"As opposed to vegetable or mineral error?"
-John Pescatore, SANS NewsBites Vol. 12 Num. 59
#40 lore raw
In reply to Drew Northup
Quoted 2 lines · Drew Northup

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

Signature · 2 lines
Happiness, n. An agreeable sensation arising from contemplating the misery of
another.
#41 lore raw
Quoted 7 lines · Miles Bader
Quoted 2 lines · Drew Northup

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?

Signature · 5 lines
-Drew Northup N1XIM
   AKA RvnPhnx on OPN
________________________________________________
"As opposed to vegetable or mineral error?"
-John Pescatore, SANS NewsBites Vol. 12 Num. 59
#42 lore raw
In reply to Thore Husfeldt
Quoted 4 lines · Thore Husfeldt

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)

Quoted 2 lines

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.

Quoted 3 lines

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.

Quoted 4 lines

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.

Quoted 8 lines

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

Quoted 3 lines

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

Quoted 4 lines

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.

Quoted 4 lines

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.

Signature · 2 lines
Matthieu Moy
http://www-verimag.imag.fr/~moy/
#43 lore raw
Quoted 3 lines · Matthieu Moy

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

Signature · 1 line
Do not taunt Happy Fun Ball.
#44 lore raw
Quoted 5 lines · Miles Bader

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

#45 lore raw
Quoted 1 line · Wincent Colaiuta

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

Signature · 1 line
Cat is power.  Cat is peace.
#46 lore raw
Quoted 6 lines · Miles Bader
Quoted 1 line · Wincent Colaiuta

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

Quoted 8 lines

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

#47 lore raw
Quoted 6 lines

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

#48 lore raw
Quoted 7 lines · Eugene Sajine

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

#49 lore raw
Quoted 20 lines · Paul Bolle
Quoted 7 lines · Eugene Sajine

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
Quoted 8 lines

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

#50 lore raw
Quoted 45 lines · Eugene Sajine
Quoted 20 lines · Paul Bolle
Quoted 7 lines · Eugene Sajine

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
Quoted 8 lines

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

Quoted 7 lines

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.

Signature · 5 lines
-Drew Northup N1XIM
   AKA RvnPhnx on OPN
________________________________________________
"As opposed to vegetable or mineral error?"
-John Pescatore, SANS NewsBites Vol. 12 Num. 59
#51 lore raw
In reply to Matthieu Moy
Quoted 6 lines · Matthieu Moy

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

Quoted 1 line

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

(Or using git branch). Git tells her that

Quoted 1 line

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:

Quoted 1 line

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:

Quoted 6 lines

### 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

Quoted 5 lines

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

#52 lore raw
Quoted 3 lines · Thore Husfeldt
Quoted 1 line

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.

?

Quoted 4 lines

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.

Quoted 2 lines

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)

Signature · 2 lines
Matthieu Moy
http://www-verimag.imag.fr/~moy/
#53 lore raw
Quoted 11 lines · Matthieu Moy
Quoted 4 lines · Thore Husfeldt

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?

Signature · 4 lines
-Drew Northup
________________________________________________
"As opposed to vegetable or mineral error?"
-John Pescatore, SANS NewsBites Vol. 12 Num. 59
#54 lore raw

PATCH v3 1/1 Porcelain scripts: Rewrite cryptic "needs update" error message

In reply to Thore Husfeldt

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.

---
Ref: <[email protected]> for v2.
Ref: <[email protected]> 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(-)
git-pull.sh +1 -4
index 8eb74d4..20a3bbe 100755
@@ -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 &&
git-rebase--interactive.sh +3 -11
index a27952d..4d8a2a0 100755
@@ -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
git-rebase.sh +1 -13
index e5df23b..988b3d8 100755
@@ -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
git-sh-setup.sh +29 -0
index ae031a1..aa16b83 100644
@@ -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 /{
Signature · 1 line
1.7.2.2.409.gdbb11.dirty
#55 lore raw

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

Hi,

Quoted 10 lines · 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.

Quoted 7 lines

---
Ref: <[email protected]> for v2.
Ref: <[email protected]> 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

#56 lore raw

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

Quoted 15 lines · Ramkumar Ramachandra
Quoted 14 lines · 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.

---
Ref: <[email protected]> for v2.
Ref: <[email protected]> for v1.

Quoted 5 lines
Quoted 3 lines

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.

#57 lore raw

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

In reply to Ramkumar Ramachandra
Quoted 5 lines · Ramkumar Ramachandra

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

#58 lore raw
In reply to Thore Husfeldt
Quoted 4 lines · Thore Husfeldt

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

Quoted 10 lines

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.

Quoted 20 lines

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.

Quoted 13 lines

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.

Quoted 9 lines

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

Quoted 5 lines

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

Quoted 2 lines

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

Quoted 9 lines

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.

Quoted 6 lines

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.

Quoted 1 line

The remote branch?

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

Quoted 1 line

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.

Quoted 1 line

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!

Quoted 9 lines

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.

Quoted 6 lines

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.

Quoted 6 lines

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.

Quoted 4 lines

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

Quoted 8 lines

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

Quoted 5 lines

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.

Quoted 7 lines

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.

Quoted 2 lines

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

Quoted 6 lines

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.

Quoted 2 lines

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.

Quoted 3 lines

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.

Quoted 10 lines

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.

Quoted 3 lines

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.

Quoted 8 lines

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.

Quoted 7 lines

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.

Quoted 4 lines

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.

Quoted 6 lines

Here are some concrete suggestions:

1.

nothing added to commit but untracked files present

Quoted 8 lines

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?).

Quoted 8 lines

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.

Quoted 9 lines

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.

Quoted 12 lines

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.

Quoted 4 lines

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.

Quoted 5 lines

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

Quoted 8 lines

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

Quoted 4 lines

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.

Quoted 4 lines

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.

Quoted 9 lines

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.

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