On Tue, Sep 3, 2013 at 11:23 PM, Drew Northup <n1xim.email@xxxxxxxxx> wrote: > On Fri, Aug 30, 2013 at 1:16 AM, Piotr Krukowiecki > <piotr.krukowiecki@xxxxxxxxx> wrote: >> Drew Northup <n1xim.email@xxxxxxxxx> napisał: >>>I agree with Junio. This effort is better spent making the >>>documentation clearer and more succinct. The reality is that a user >>>needs to build a model in their mind of what they are doing which maps >>>enough (completely is not required) to what is actually going on to >>>get work done. If the documentation or the instruction is getting in >>>the way of that in the name of simplifying the presentation then the >>>presentation is wrong. >> >> Why do you think the "stage" model do not map enough? > > When I try to explain how to use git to complete VCS newbies in > general they find the "snapshot" model more mentally sensible than the > "staging area" model. (In other words, the user doesn't care how, if, > or where the program is maintaining state.) The snapshot concept is totally orthogonal from the staging area concept. Git works in snapshots, which are frozen images of how the content tree was at a certain point in time; IOW; a commit. _How_ that snapshot is created is an entirely different topic, and the staging area is a tool to create the desired snapshots. The user might decide to never use that tool (i.e. always run git commit -a), but the concept of snapshots remain. So, clearly, one concept has absolutely nothing to do with the other. >>>We add content snapshots to the index of content (creating >>>"temporary"--they will be garbage collected eventually if they become >>>orphans--objects into the store at the same time). We build commits >>>from those snapshots (in whole or in part, typically only using the >>>most recent snapshots of new things added to the index) and save those >>>in the object store with the content and tree objects. Sometimes we >>>create tag objects to record something special about commits, trees, >>>and content blobs. >> >> The above can be rewritten to use the 'staging area' concept just >> fine. And I don't think you should say to inexperienced users things >> like 'tree objects'. > > At what time did I say specifically what I tell newbies? I did not do > so. Please refrain from making that sort of assumption. In any case, > no, you cannot rewrite that to use "staging area" in place of "index" > without introducing a different mental model and new concept into the > text (a model which happens to be incomplete, but not incorrect). That > minimalist summary was written for the technically-minded people here > on this list debating the issue of communications with the users--the > bane of all programmers' lives. You are mixing useful mental models for the majority of Git users, and technical implementation details. You say what you wrote is for technically-minded people, and those people are not relevant for this discussion, because we are not talking about the implementation details, we are talking about the vast majority of Git users, so stop with the red herrings. The "mental model" of staging area is an area that is used for preparation for something, and that's *exactly* what the vast majority of users think of the index as a high-level concept. > Again, let us keep our argument focused on communications with users. > Renaming core objects is just going to sow confusion without fixing > the user communication issue. That's what I meant the first time I > wrote what I quote directly above and I'm sticking to it. The vast majority of Git users have absolutely no clue about what's the index. That's why online documentation uses the term "staging area", so in fact we would be reducing confusion, by a lot. -- Felipe Contreras -- 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