Git terminology: remote, add, track, stage, etc.
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.
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 unstageforgit reset HEADin 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
cachedflags asstaged(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
[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
@@ -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
@@ -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
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 addfoo.c
rmfoo.c; # bad file! bad!
git resetfoo.cThe file
foo.cdoes 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 revisionsGit can do better: since
foo.cis not a revision and has an entry in the index, it is clear the request refers to a path and not a rev.Signed-off-by Jonathan Nieder <[email protected]>---
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@@ -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.
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 inverify_non_filename()itself.
Yes.
Is it safe to load the index so early? I can imagine a person trying "git reset" to recover from a corrupted index; are we regressing in that respect and how would one check for it?
Re: [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 inverify_non_filename()itself.Yes.
Is it safe to load the index so early? I can imagine a person trying "git reset" to recover from a corrupted index; are we regressing in that respect and how would one check for it?
It is generally unsafe, I am afraid, and that is one of the reasons why verify_filename() does not look in the index (the other one was "it is merely a safety measure based on heuristics to help users, and no point spending extra code nor cycles", iow, deliberate laziness ;-)), making the proposal of this patch under discussion somewhat iffy.
Re: [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.
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 unstageforgit reset HEADin 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. Maybegit 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
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.
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
@@ -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
@@ -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
@@ -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
@@ -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
@@ -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
@@ -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
@@ -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
@@ -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
@@ -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
@@ -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
@@ -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
@@ -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
@@ -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
@@ -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
@@ -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
@@ -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
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
@@ -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 )
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.cwhile 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.
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
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
@@ -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
@@ -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
PATCH 2/4 reset: accept "git reset <tree> <path>"
In reply to Jonathan NiederThe <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
@@ -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
@@ -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
PATCH 3/4 reset: accept "git reset -- <path>" from unborn branch
In reply to Jonathan NiederA 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
@@ -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
PATCH 4/4 reset: accept "git reset HEAD <path>" from unborn branch
In reply to Jonathan NiederIf 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
@@ -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
@@ -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
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.
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
_nosuchcommit_. 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.
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
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.
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
@@ -359,13 +359,16 @@ $ git branch -r origin/todo ------------------------------------------------ -You cannot check out these remote-tracking branches, but you can -examine them on a branch of your own, just as you would a tag: +You might want to build on one of these remote-tracking branches +on a branch of your own, just as you would a tag: ------------------------------------------------ $ git checkout -b my-todo-copy origin/todo ------------------------------------------------ +You can also check out "origin/todo" directly to examine it or +write a one-off patch. See <<detached-head,detached head>>. + Note that the name "origin" is just the name that git uses by default to refer to the repository that you cloned from.
Re: 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/
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
Hi,
Quoted 10 lines · Ramkumar Ramachandra
From
a863e58d240956191c2fa9cbe992aaca5786730bMon 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.
Reported-by Thore Husfeldt <[email protected]>Signed-off-by Ramkumar Ramachandra <[email protected]>
and
Quoted 5 lines
From
7422c2af1ef40c922d8f628715ad96172e4a5734Mon 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.
Reported-by Thore Husfeldt <[email protected]>Signed-off-by Ramkumar Ramachandra <[email protected]>
Junio: Are these patches suitable for inclusion?
-- Ram
Quoted 26 lines · Ramkumar Ramachandra
Hi,
Quoted 10 lines · Ramkumar Ramachandra
From
a863e58d240956191c2fa9cbe992aaca5786730bMon 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.
Reported-by Thore Husfeldt <[email protected]>Signed-off-by Ramkumar Ramachandra <[email protected]>and
Quoted 10 lines
From
7422c2af1ef40c922d8f628715ad96172e4a5734Mon 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
Reported-by Thore Husfeldt <[email protected]>Signed-off-by Ramkumar Ramachandra <[email protected]>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
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/
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
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/
Quoted 11 lines · Thore Husfeldt
Ive 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 its worth. Read it as the friendly, but somewhat exasparated suggestions of a newcomer. Id love to help (in the form of submitting patches to the documentation or CLI responses), but Id 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 undergit 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 dont 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 origins master. Id 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 thats 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 unstageforgit reset HEADin 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
cachedflags asstaged(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 calledtracking the file') and `staging for the next commit' result in the exact same operations, from Gits perspective.
Quoted 5 lines
But this is a good example of whats wrong with the way the documentation thinks: Gits 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 Gits worldview) and un-staging are not the same thing at all, neither conceptually nor implementationally. The opposite of staging isgit reset HEAD <file>and the opposite of tracking is -- well, Im not sure, actually. Maybegit 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 stageis already a synonym forgit 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, thatgit addandgit stage*are* indeed synonyms, because of Gits 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 trackas another alias forgit add. (See above undergit 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
Theres another issue with this, namely that added files are immediately staged. In fact, I do understand why Git does that, but conceptually its 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 thats 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
Quoted 8 lines
* The
--cachedoption 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--cachedoption, it looks for strings in the index.
Quoted 6 lines
* The
--indexoption is used to ask a command that usually works on files in the working tree to *also* affect the index. For example,git stash applyusually merges changes recorded in a stash to the working tree, but with the--indexoption, 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
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
--cachedoption 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--cachedoption, 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
--indexoption is used to ask a command that usually works on files in the working tree to *also* affect the index. For example,git stash applyusually merges changes recorded in a stash to the working tree, but with the--indexoption, 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
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*.
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 Gits 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
Gits 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 systemss 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 Gits 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; its almost as nice, and I dont 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 didnt 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 origins 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
Im not sure I like the particular word, but thats a minor complaint.
( For completeness: A small terminological quibble is that upstream doesnt 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 gits 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_ideasis bob/master", and for Bob to say "the upstream ofalices_inane_ramblingsis 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
Quoted 6 lines · Jakub Narebski
Well, there is different suggestion: make
git stage,git trackandgit mark-resolvedto be *specializations* ofgit 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/
Quoted 11 lines · Michael Haggerty
Quoted 6 lines · Jakub Narebski
Well, there is different suggestion: make
git stage,git trackandgit mark-resolvedto be *specializations* ofgit 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
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.
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
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”.
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
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.
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
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
cachedflags asstaged(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. Maybegit 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 trackas another alias forgit add. (See above undergit 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/
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.
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
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.
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
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
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
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_masterjd_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
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_BAZQuoted 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 - localremote from user
$ git remote add jdoe ~jdoe/project/.gitThen remote-tracking branches will be
jdoe/master
jdoe/featurexmy local branches tracking remote-tracking branches (automatic push, pull)
jd_masterjd_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_masterthat 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
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
_trackingbranch_. 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, runninggit pullwhile 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
masterbranch that tracksorigin/master. That’s whygit pushandgit pullwork 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 onoriginand don’t track themasterbranch. The simple case is the example you just saw, runninggit checkout -b [branch] [remotename]/[branch]. If you have Git version 1.6.2 or later, you can also use the--trackshorthand:
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, runninggit pullon 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
masterbranch whose upstream branch is the remote-tracking branchorigin/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.
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/
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 branchI 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
PATCH v3 1/1 Porcelain scripts: Rewrite cryptic "needs update" error message
In reply to Thore HusfeldtAlthough 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
@@ -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
@@ -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
@@ -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
@@ -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
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-indexis run, with a more friendly message.Reported-by Joshua Jensen <[email protected]>Reported-by Thore Husfeldt <[email protected]>Signed-off-by Ramkumar Ramachandra <[email protected]>
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
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-indexis run, with a more friendly message.Reported-by Joshua Jensen <[email protected]>Reported-by Thore Husfeldt <[email protected]>Signed-off-by Ramkumar Ramachandra <[email protected]>---
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.
Re: [PATCH v3] Porcelain scripts: Rewrite cryptic "needs update" error message
In reply to Ramkumar RamachandraQuoted 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.
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 addbelow.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 stageis 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 unstageforgit reset HEADin 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
cachedflags asstaged(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. Maybegit 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 trackas another alias forgit add. (See above undergit 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