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