From: Sverre Rabbelier Date: Mon, 18 Oct 2010 21:35:32 GMT Subject: Re: Git terminology: remote, add, track, stage, etc. Message-ID: In-Reply-To: <8835ADF9-45E5-4A26-9F7F-A72ECC065BB2@gmail.com> Heya, [+Scott, who's done a lot of work on making git more newbie friendly] [+Jonathan, I saw his reply just before sending this] On Mon, Oct 18, 2010 at 15:45, Thore Husfeldt wrote: > I’ve just learned Git. What a wonderful system, thanks for building > it. Thanks. > And what an annoying learning experience. Thanks again :). > I promised myself to try to remember what made it all so hard, and to > write it down in a comprehensive and possibly even constructive > fashion. Here it is, for what it’s worth. Read it as the friendly, but > somewhat exasperated suggestions of a newcomer. I’d love to help (in > the form of submitting patches to the documentation or CLI responses), > but I’d like to test the waters first. Awesome! Your experiences are very welcome indeed! > So, remote tracking branches are neither remote (they are *local* > copies of how the remote once was) and they stand completely still > until you tell them to “fetch”. So remote means local, and tracking > means still, “local still-standing” would be a less confusing term > that “remote tracking”. Lovely. *chortles*, nicely observed. > The hyphenated *remote-tracking* is a lot better terminology already > (and sometimes even used in the documentation), because at least it > doesn't pretend to be a remote branch (`git branch -r`, of course, > still does). What do you mean with the last part (about `git branch -r`)? The fact that 'refs/remotes' is not immutable? > So that single hyphen already does some good, and should > be edited for consistency. If we agree that "remote-tracking" is the way to go, a patch doing such editing would be very welcome. > And *even if* the word was meaningful and consistently spelt, the > documentation uses it to *refer* to different things. Assume that we > have the branches master, origin/master, and origin’s master > (understanding that they exist, and are different, is another Aha! > moment largely prevented by the documentation). How could the documentation make this more clear? > Or rather, it is the confirmation one needs that nobody in the Git > community cares much On the contrary, we care a lot, but once you're not a new user yourself anymore, it's hard to know what to fix. > There probably is a radical case to be made for abandoning the word > “tracking” entirely. First, because tracking branches don’t track, and > second because “tracking” already means something else in Git (see > below). I realise that this terminology is now so ingrained in Git > users that conservatism will probably perpetuate it. But it would be > *very* helpful to think this through, and at least agree on who > “tracks” what. In the ideal world, origin/master would be something > like “the fetching branch” for the origin’s master, or the “snapshot > branch” or the “fetched branch”. > [...] > More radically, I am sure some head scratching would be able to find > useful terminology for master, origin/master, and origin’s master. I’d > love to see suggestions. As I said, I admire how wonderfully simple > and clean this has been implemented, and the documentation, CLI, and > terminology should reflect that. I don't have any objections to changing these terms, but I don't have any suggestions on what to change them _to_. > 2. Introduce the alias `git unstage` for `git reset HEAD` in the > standard distribution. (or 'git rm --cached' for newly added files) >    nothing added to commit but untracked files present > > should be > >    nothing staged to commit, but untracked files present I've always liked the whole 'stage(d)' concept, so I like this, but I remember Junio being fairly hesitant to use it more extensively. > (Comment: maybe “... but working directory contains untracked files.” > I realise that “directory” is not quite comprehensive here, because > files can reside in subdirectories. We use "worktree" elsewhere, how about that? >    (use "git track " to track) So basically you want to split out 'git add' into 'git track' and 'git stage'? >    Changes to be committed: >    (use "git reset HEAD ..." to unstage) > > should be > >    Staged to be committed: >    (use "git unstage " to unstage) This would be extra nice since 'git unstage' could also be used in a fresh repository. > But this is a good example of what’s wrong with the way the > documentation thinks: Git’s implementation perspective should not > define how concepts are explained. In particular, *tracking* (in the > sense of making a file known to git) and *staging* are conceptually > different things. In fact, the two things remain conceptually > different later on: un-tracking (removing the file from Git’s > worldview) and un-staging are not the same thing at all, neither > conceptually nor implementationally. Fair point, I think. > The opposite of staging is `git > reset HEAD ` and the opposite of tracking is -- well, I’m not > sure, actually. Maybe `git update-index --force-remove `? 'git rm --cached' > The entire quoted paragraph in the tutorial can be removed: there’s > simply no reason to tell the reader that git behaves differently from > other version control systems I disagree, many people come from another VCS, and pointing out where their assumptions are invalid is generally useful. > There’s another issue with this, namely that “added files are > immediately staged”. In fact, I do understand why Git does that, but > conceptually it’s pure evil: one of the conceptual conrnerstones of > Git -- that files can be tracked and changed yet not staged, i.e., the > staging areas is conceptually a first-class citizen -- is violated > every time a new file is “born”. Newborn files are *special* until > their first commit, and that’s a shame, because the first thing the > new file (and, vicariously, the new user) experiences is an > aberration. Eh, I think it's not an aberration, it's more of a convenience. I don't think the benefit of making the concept of tracking vs. staging clear to the user is worth the hassle of having to execute two things to do one thing (staging a new file). You can also see it the other way around, why are new files any different from other files? Why shouldn't you be able to stage new files? -- Cheers, Sverre Rabbelier